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Alternative Programming Languages CD-ROM 



This CD-ROM is your definitive 
resource for the latest in cutting- 
edge programming environments. 
Gain access to the most innovative, 
solution-providing languages and 
tools available today! 



Exaenine the next generation off languages 

You need this tool 10 get up to speed on distributed computing, All these languages are robust, imaginatively designed, break new 

embeddable languages, increased productivity, and languages of technical ground, and come with source code for compilers or 
the future. interpreters. .And you also get the full descriptions and specifications. 


You get all these languages, compilers, interpreters - Perl, 

Glish, Smalltalk, Sather, Tel, MO, Modula-3, ReXX, Lout, 

Ghostscript, Dylan, Duel, Bob, Neudl, Python, Oberon, 

Parasol, S-Lang. Quincy, uSystcm, Distributed C, the GNU 

compiler suite—and more! 

Put tliis CD-ROM to work immediately on your development projects: 

• Object-Oriented Development. Tired of C++? Look no 
further than Sather, Dylan or Bob and get re-energized. 

• Distributed Computing. When building distributed sys¬ 
tems, languages like Parasol and MO make your life easier. 

<§ Multiple Platforms. Check out Perl and Python, plus a 
wide range of compilers, including the GNU compiler suite. 

f Text Processing and Document Formatting. 

Lout and Ghostscript let you edit and produce complex 
documents with ease. 

3 Prototyping. When prototyping connected distributed 
systems, Glish makes it all happen for you. 

3 Neural Networks. Neudl takes the pain out of building 
complex neural networks. 

3 And much more! 



SPECIAL BONUS! 

With your purchase of this CD-ROM, you’ll also 
receive a copy of the Dr. Dobb’s Sourcebook, 
Alternative Programming Languages 
A $4,95 value —ABSOLUTELY FREE! 


YES! Send me the Dr. Dobb's Alternative 


| Programming Languages CD-ROM immediately. 

■ 1 will also receive the Dr : Dobb's Sourcebook 

- Alternative Programming Languages as a bonus. 

1 (Vly price is S49.95 (plus shipping; $2.00 U.S./Canada; all other 
| countries $15*00). California residents, pfease add S4.25 sales tax. 

■ Clip out or photocopy this form. 


■ Name 


1 Address 


® City/State/Zip 


■ Country 

■ Here's how I'm paying (circle one); VISA - MC - AMEX ■ Check enclosed 


| Credit card number {include all digits) Expiration Date 




gnature required 



For more 

Alternative Programming 

infonnation, 

languages CD 

send E-Mail to: 

info_altcd@mfi.com 


FREE CALL: 800-407-2587 24 HOURS A DAY, 7 DAYS A WEEK FAX ORDERS: $10-872-8582 

E-MAIL ORDERS: order_CDROM@MFI.CGM MAIL ORDERS: ALT CD r P.O. Box 1525, Martinez, CA 94553 
INTERNATIONAL: USE MAIL, FAX 510-372-8582, E-MAIL order_CDROM@MFI.COM, OR CALL 415-655-4252 





















Send me the Essential Books on Graphics 
Programming CD-ROM immediately* 


You can't get more graphic than this. 


Introducing the 

Essential Boohs on Graphics Programming CD-ROM 

I from the Dr. Dobb’s CD-ROM Library 


Nc 


I eed to gel up to speed on graphics programming-fast? There's 
only one definitive source you can turn to -Dr Dobbs Essential 
Books on Graphics Programming CD-ROM! 

Get seven of the essential books in graphics programming, with full 
text* diagrams, graphics, and source code-all on one CD-ROM. From 
fundamental algorithms to the most complex techniques, this CD-ROM 
lets you find ail the critical information you need for your graphics 
programming projects. 


Texture mapping, color modeling, and mor¬ 
phing, all optimized for speedy 2-D and 
3-D graphics programming. Practical 
image acquisition and processing. 
High-quality 3-D photorealistic 
graphics. Digital halftoning. 

Image synthesis and special 
effects. 


And much more! 

Plus, all the source code on 
the disks supplied with die 
books are included. 

Your CD-ROM comes with 
must-have features: 

• a powerful search engine for 
locating information across all or 
selected books 


• tables of contents and indexes hotlinked to 
their topics 

• copy, bookmark, and notes functions 
And you get a full money-hack guarantee! 


Windows 

Platform 


Si wtt V 


ONLY $69.95 PLUS SHIPPING 


: 510-372-8582 USE THIS ORDER FORM. 

:RSi order_CDROM@MFJ.COM 

S: Dr. DobbVCD. RO. Box 1525, Martinez, CA 94553 9802 
USE MAIL, FAX, E-MAIL, OR CALL 415-655-4252 


My price is $69,95 (plus shipping: $2.00 U.SJCanada; all other countries $15.00). 
California residents, please add $5.95 sales tax. Clip out or photocopy this form, 1 


Name 


I Address 


| City/State/Zip 


I Country 

Here’s how I'm paying (circle one): VISA - MC * AMEX - Check enclosed 


Credit card number (include all digits) 


Expiration Date 


Signature required 


























In the Race for Solutions, 

Finish First 



Introducing VisPro/Reports, the first programmable 
report writer for VisPro/REXX, VX REXX and OS/2 REXX 


On April 28,1993 HockWare Inc. shipped 
VisPro/REXX, the first OS/2 visual programming 
tool for REXX, Since then, we've achieved many 
other firsts. VisPro/REXX t VisPro/C and 
Vi$Pro/C++ are the first REXX, € and C++ tools 
to incorporate drag and drop programming, an 
entity-relationship database designer, and a rich 
set of add-on objects including: spreadsheet, 
business graphics, formatted entry 1 field, dock 
and calendar. Whether you're using REXX, 
C-Presentation Manager, or IBM’s User-Interface 
Class Library, there is a VisPro product to meet 
your needs. 


• Banded report options allow you to choose 
from a rich set of headers, footers and groups. 

• Label reports allow you to select from a large 
list of Avery labels, 

• Support for multiple line text, derived fields, 
business graphics, bitmap images, rectangles, 
lines and ellipses. 

• Many object properties to choose from, 
including any OS/2 font, 16 million colors, line 
styles, fill patterns and drop shadows, 

• Wide selection of field options, International 
currency 1 and formulas. 

• Numerous sample reports included. 



Yet .Another First 

VisPro/Reports is the latest addition to 
the VisPro family of OS/2 
programming products. 

VisPro users will recognize 
the easy-to-use CUA’91 
user-interface and the drag 
drop style HockWare pioneered 
years ago. 

Designing Reports is Easy 
# WYSIWYG, free-formal report design tool. 






Report Printing is Easy 

* Seamlessly print or preview reports 
from any OS/2 REXX environ¬ 
ment including VisPro/REXX, 

\X REXX and plain OS/2 REXX. 

* Use your favorite REXX- 
enabled databases and third 
party libraries for access to DB2, 
.DBF files, EHLLAPI mainframe 
connections and more. 

■ A runtime DLL of less than 100K 
can be distributed royalty free. 


The Complete VisPro Family 

VisPro/Reports.$199 

VisPro/REXX Gold...*.$299 

VisPro/REXX Bronze.,,,. $ 59 

VisPro/REXX Data Entry Object Pack . * $>f? $ 89 
VisPro/C or VtePra/€++ SPECIA1II! $199 

VisPro Development Suite-... $499 

(includes VisPro/REXX Gold, C and C++) 


Whether you've already discovered the VisPro 
family of visual programming products or you're 
just getting to know us, meet j 
our latest member, 

VisPro/Reports. .And be 

the first to get where _ _ 

you're going. 


rtf* 




Nlinji Yh.w in (uniml 


HockWare In torpor ate d 

P,Q> Box 336 

Canf. KC 27S12-0336 

919 - 380-0616 

919-380-0757 FAX 

Go HockWare on CompuServe 

hockware@vneLnet on Internet 

http://www.nando.net/ads/hockware 


HockWare. VlsJPro/C, Yi$Pro/C++, VisPm/SEXX and VisPno/Repons art trademarks of HockWare Incorporated M other company, product and brand names are trademarks and/or registered trademarks of their 
respective holders and are mentioned for reference purposes only, © 1995 HockWare incorporated. All rights reserved. 









Editor 

Dick Conklin 

Managing Editor 

Theresa Mori 

Editorial Assistant 

Deborah Sommers 

Editorial Artist 

Peter Altenberg 


Group Director 

Regina Starr Ridley 

PUDLISHER 

Peter Westerman 



Advertising Sales 

Yvonne Labat 
(4150905-2353 
Stephen Nikkola 
(415) 905-2256 
Kristin Morgan 
(212) 626-2498 


Marketing Manager 

Susan McDonald 

Advertising Production 
Coordinator 

Glenn Sadin 


Vide President. Production 

Andy Mickus 

Vice President, Circulation 

jerry Okabe 


GUI 

REXX Trek-A Comparison of REXX Visual Builders 4 



COMMUNICATIONS 

E-Mail Enabling REXX 9 

PDS Transfers Using EHLLAPI in REXX 22 

OBJECTS 

Intro to Workplace Shell Programming Using REXX 13 

Object REXX-HowCool 31 

The Workplace Shell: Objects to the Core 42 

PRINTING 

Combining REXX and PostScript 17 

PERFORMANCE 

Six Simple Code-Tuning Techniques 35 

INTERNATIONAL 

Designing REXX Programs for Multiple Languages 39 


Circulation Director 

REXX 



John Rockwell 

REXX Buyers Guide 52 



Circulation Manager 

Contact 

CompuServe 

Internet 

Stephanie Blake 

Dick Conklin 

76711,1005, or 

os2mag@vnet.ibm.coin 


(Editorial) 

OS2DF2 Forum 


Subscription Inquiries 

Miller Freeman 

(Circulation) 

71572341 

71572.341©compuservecom 

U.S.: (800) WANT-OS2 

Peter Westerman 

76307,1054 

pwesterman@mfi.oom 

Foreign: (708) 647-5960 

(Publisher) 




Theresa Mori 


tmori@mfi.com 


(Managing Editor) 



OS/2 Developer VoL 7, Summer 1995 




Subscription information: U.S.: One year (six issues), $ 39,95, Canada, Mexico, and international surface mail add $16 per year for postage. Canadian GST no. 124513185. 
International air mad, add $30 per year for postage. Foreign orders must be accompanied by payments in U.S. funds. For new orders and customer service, call (800) WANT-052 
(800-926-8672) or (708) 647-5960 (fax: 708-647-0537), IBM employees and branch office customers can subscribe to OS/2 Dei*e toper through IBM Mechanicsburg s Systems Library 
Services (SLSS) using OS/2 Developer's order number: G362-0001. POSTMASTER: Please send address changes toG5/2 Developer, P.O, Box 1079, Skokie, IL 60076-8079. Allow eight 
weeks for subscriptions to begin. OS/2 Developer (ISSN 1073-0729) is published bimonthly by Miller Freeman Inc., 600 Harrison Street, San Francisco, CA 94107, (415) 905-2200, 
Application to mail at second-class postage rates is pending at San Francisco, CA and additional mailing offices. 


© Copyright 1994 by Miller Freeman Inc, PRINTED IN THE U,S, A, 


'Iff, Miller Freeman 

A United News & Media publication 







GUI 


Which REXX tool is best for you? It depends. A Trekkie reviews VX-REXX, 
VisPro REXX and GpfREXX. 

By BLAKE WATSON 


REXX Trek— 

A Comparison of 
REXX Visual Builders 


/ have used the various visual REXX 
tools almost from the beginning, and I 
sometimes get asked which of the three 
tools is the best: Watcom's VX-REXX, 
Hockware's VisPro REXX, or Gpf REXX. The 
answer is usually a firm: "It depends." 

Not only does each of the tools has its 
strengths and weaknesses, each has suffi¬ 
ciently different interfaces, whereby one tool 
might drive you nuts while another tool 
seems intuitive to you, even though both 
offer comparable features. 

To illuminate some of these differences, 
I pulled out the rusty old Star Trek game, 
which is a standard program I write to test 
out various environments. For those of you 
who don't know, the Star Trek game, devel¬ 
oped in the late 1960s at Carnegie-Mellon 
University in Pittsburgh, Pa., simulates a 
military conflict in space where the player at¬ 
tempts to destroy the alien invaders within a 
certain amount of time. The player has a lim¬ 
ited amount of energy to deploy weapons 
and shields and move through space. The 
player can refuel at outposts, which may be 
attacked and destroyed by the aliens. I can 
write this game in my sleep, which leaves 
me free to concentrate on the development 
environments and, at the same time, lets me 
test how the environment handles subrou¬ 
tines, objects, and other interesting items. 

The notes and comments expressed 
herein are based on the following versions of 
products: Gpf REXX 1.0 (level 04), Hockware 
VisPro/REXX Gold 2.03, and VX-REXX 
Client/Server Edition Version 2.1. Tests 
were done under OS/2 2.1, 2.11, and OS/2 
Warp for Windows. 

BUILDING THE GUI 

Let's start the comparison by looking at the 
basic GUI for the game. I typically design it 
as a three-window game, with a Command 


Panel (CP), from which the user issues com¬ 
mands, and two other windows, one repre¬ 
senting Long Range Scanners (LRS) and the 
other representing Short Range Scanners 
(SRS). 

Space in this game is an eight-by-eight 
grid, where each division (called a quadrant) 
is divided into an eight-by-eight grid of sec¬ 
tors. So, space consists of 64 quadrants, and 
each quadrant consists of 64 sectors. 

Figures 1, 2, and 3 show how the inter¬ 
face looks under Gpf REXX, VisPro/REXX, 
and VX-REXX, respectively. The CP is usu¬ 
ally just a window full of buttons and text 
controls, and the two sensor windows work 
nicely as value sets. 

As you can see. I've modified the game 
slightly from its traditional format to make it 
easier to use. The commands are actually is¬ 
sued from the LRS and SRS windows: The 
user clicks on the value set to the right to in¬ 
dicate a command (on the SRS, set destina¬ 
tion, go, target phasers, and target photons; 
on the LRS, set destination and go) and then 
double-clicks on a spot on the value set to in¬ 
dicate the desired location. The command 
panel is only used to offer information and 
set the phaser and shield strength. Now 
we'll look at the issues that arose while 
building each of the interfaces under the var¬ 
ious products. 

GPFREXX 

The interface Gpf REXX uses is very OS/2 
1.3 oriented, and yet the polish of time 
shows up when you use it. Yes, it's heavily 
menu and dialog driven, but while this 
makes it somewhat less aesthetic, perhaps, it 
doesn't typically make it harder to use. In 
some ways, in fact, it seems easier to use— 
perhaps only because it is based on Gpf's C 
GUI builder, which is one of the oldest 
around for OS/2. 
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One place where it is definitely harder 
to use than the other two is in the setting up 
of a value set, Gpf requires a name for each 
cell in the value set or you cannot access that 
cell at run time. To add a component to a 
Gpf value set, you start from a dialog show¬ 
ing a listbox of all components for that value 
set, then you click on an Add button to bring 
up a dialog for that component, and then 
you click OK to dismiss the dialog. 

Naming 64 cells (twice) was the least- 
pleasant aspect of working with Gpf. In fact, 
I didn't do it. I just accepted the default 
names that Gpf supplied and wrote the code 
to work around those names (which are for¬ 
tunately serial). 

Actually, the least-pleasant aspect of 
working with Gpf is reserved for those using 
542x Cirrus cards under OS/2 2.1 or 2.11. 
Gpf and the old Cirrus drivers do not co¬ 
habit well, and that will be extremely un¬ 
pleasant. Under Warp, those problems van¬ 
ish, however. 

One of the more pleasant aspects of 
working with Gpf REXX was its recognition 
and handling of presentation parameters. 
Gpf stands out from the other products in its 
ability to create and work with presentation 


parameters. (You can assign a group of con¬ 
trols the same presentation parameters and 
give them a common look and feel far more 
easily than you can setting each control's in¬ 
dividual color and font fields.) 

Even under Gpf though, you couldn't 
change a group of controls all at once so that 
they all shared the same presentation para¬ 
meters. (Unfortunately, none of the tools 
would let you group change the attributes of 
an object—except for size and position— 
which makes creating a consistent nonde¬ 
fault look between the controls a real pain in 
VX-REXX and VisPro/REXX.) So even when 
programming with Gpf, the first thing you 
would do is define what controls are going 
to look alike and assign them a presentation 
parameter when you created them. Then 
later, you would go back and modify the 
presentation parameters to customize the 
look of your application. 

Of the three products, Gpf seems to ac¬ 
knowledge the underlying API the most. For 
example, you can place a label control on 
your form, then with a dick of a dialog set¬ 
ting change it to any of the valid forms of 
the WC_STATIC window class. In other 
words, you can turn your label into a 



1 !i *J|[. “J Lf .iL-iLLJ'' F .A h jI 


p 

EC 

E 


LlH 

T G 


a 

PI P2 


h 

E 

P3 PA 


E 

P5 PB 


m 

Tt T2 


E 

T3 14 



= Command Pam t 


n 


. C3 CJ 

B 

; [ B L 

CTB 


Figure /. How the interface looks under Gpf REXX, 
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bitmap, a rectangle, or whatever. This 
can give you a very strong feeling of 
control, especially if you are comfort¬ 
able with the PM APL Of the three 
products, I can also only nervously 
recommend Gpf, for while it is a good 
product, it is still at 1.0 after well over 
a year in release. 


VX-REXX 

Setting up the program in VX-REXX 
was a breeze, for the most part. Unlike 
the dialog/menu-oriented Gpf REXX, 
VX-REXX has lots of windows, which 
can actually make it difficult to find 
your way around when developing an 


application with three windows of its 
own. I often found myself moving sec¬ 
ondary windows around to get to the 
environment's main window. 

The VX-REXX environment 
strikes me as somewhat Windows-y. A 
better description might be Visual 
Basic-y. I've heard Visual Basic pro¬ 
grammers can sit right down with VX- 
REXX and feel completely at home. 
This can be a good point and a bad 
point, depending on how much of an 
OS/2 snob you are. I've never used 
Visual Basic, so I was initially annoyed 
by what seemed to be a nonOS/2 way 
of doing things. But VX-REXX is 



Figure 2. How the interface looks under VisPro/REXX. 



Figure 3, How the interface looks under VX-REXX, 


hardly difficult to get used to, despite 
this* 

Of the three products, VX-REXX 
has two oddities that stand out First, 
there is no default sizing option in the 
menu. Watcom representatives have 
told me that VX-REXX is entirely user- 
configurable, and you can actually add 
a sizing option to the menu using a 
macro you can download from their 
forum on CompuServe. 

Second, the copy option requires 
you to use the clipboard. Both VisPro 
and Gpf have drag-and-drop copy 
methods, but in VX-REXX you must 
select an object, copy it to the clip* 
board, and paste it back in. 

Also, 1 found what appeared to 
me to be a bug in the VX-REXX envi¬ 
ronment. When I gave my value set 
too many items {by accident), the con¬ 
trol vanished* VX-REXX gave it a size 
and location of zero* In the process of 
trying to resize it, I accidentally 
closed the settings notebook, and the 
control was lost to me forever. To 
save my work and not be stuck with 
an invisible orphan control, I had to 
copy the other controls to the clip¬ 
board, delete the old window, create a 
new window, and copy the controls 
back in. 

Fortunately, it wasn't a complex 
form. Nonetheless, this incident was 
disturbing. 

ViSPRQ/REXX 

VisPro/REXX is the best WPS-oriented 
designer of the three. In fact, it's one of 
the best WPS applications I've seen. 
But even this cuts two ways. For exam¬ 
ple, you can't resize a control with 
both mouse buttons like you can in 
WPS, which is a minor thing, but jar¬ 
ring precisely because you're expect¬ 
ing everything to work exactly like 
WPS does* 

And talk about multiple windows! 
VisPro/REXX does everything with 
folders and views, so you can have 
three views open on one window of an 
application, and you'll always have at 
least one additional folder open, and 
probably two or more, to contain your 
project files. 

VisPro/REXX requires you to use 
your WPS management skills to the 
fullest. When you're done with a win¬ 
dow, for example, you dose it— even 
if you might come right back to it in a 
few minutes. They don't take long to 
open, and this practice helps you keep 
your desktop clean. 

I ran into a kind of "that's good 
but*.." phenomenon a lot while work¬ 
ing with VisPro/REXX. For example, 
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options for a placed component are set 
by opening up a settings notebook. 
Very WPS-like, which is good. 

At the same time, setting some¬ 
thing in the settings notebook did not 
necessarily mean that it would actually 
change. The settings notebooks were 
generally not as reliable as doing 
something programmatically at run 
time. 

Also, sometimes, in changing the 
settings of many objects at once, it was 
easy to regret calling up several dozen 
settings notebooks at once. In fact, if 
there were too many, they would all 
collapse back down. 

I found another good example of 
good news/bad news in the value set 
control* VisPro/REXX was the only 
environment that allows accessing a 
value set by row and column, which 
was great. At the same time, there was 
no way to initialize the value in the 
value set, and VisPro/REXX doesn't 
support bitmaps at design time. 

Of the three, VisPro/REXX is the 
most ragged, in that it is most likely to 
do something unexpected or unde¬ 
sired. The controls don't always snap 
to the grid, giving some created win¬ 
dows an uneven look. Also, given two 
items at the same location, Vis¬ 
Pro/REXX takes the one underneath 
when you click on the location. 

CODING THE APPLICATION 

The biggest disappointments from all 
three tools came when I went to inte¬ 
grate actual REXX code into the GUIs. 
Two layers of code are really involved: 
the first is actual domain code, used to 
implement the game rules, and the sec¬ 
ond is code used to interface the do¬ 
main code with the GUI. 

Of course, the latter is completely 
different from product to product, as 
you might reasonably expect. The tools 
were not really built with interproduct 
compatibility as a consideration. 

But the tools were not built with 
the idea that you would have a set of 
REXX functions in one or more text 
files that could be maintained sepa¬ 
rately from the GUI code. Gpf REXX 
and VX-REXX let you stash your sub¬ 
routines in "precompiled" function li¬ 
braries, which is handy, but neither of 
these environments will (for example) 
create one of these libraries from your 
text files and let you pick from rou¬ 
tines graphically* It's all done the old- 
fashioned way. 

My main hope at this point is that 
OO REXX will aid in this area and that 
it will be possible to set up class defini¬ 
tions that all three can call and, 


thereby, minimize compatibility prob¬ 
lems. In fact, I imagine OO REXX 
could define a "standard GUI class li¬ 
brary" that all three could conform to, 
perhaps letting users port all their 
code painlessly from product to prod¬ 
uct. Now I'll discuss some specific sit¬ 
uations I encountered implementing 
the program with the three products. 

GPF REXX 

Gpf REXX has my favorite approach to 
handling basic component manipula¬ 
tion calls .You often don't have to do it 
at ail. Instead, you get an "action" tree 
that lets you plug in certain actions to 
certain events. To get the SRS and LRS 
windows to open with the CP win¬ 
dow, I just clicked on a tree branch to 
indicate the event and then selected 
from a list box of possible actions. 

The list box includes your own 
user function "objects," as they call 
them, which means you'll never miss a 
function name when interacting with 
Gpf REXX. Unfortunately, the "User 
Function" item of the list box—the one 
you'll select the most—is always at the 
end, so you always have to scroll 
down to the bottom to select it* 

Domain subroutines in Gpf are in¬ 
tegrated with the program file—you 
have to cut and paste your existing 
routines into your new Gpf REXX pro¬ 
grams, The program file itself is in a 
proprietary format. For some people, 
this is a big drawback. For me, since I 
have to paste in my own routines any¬ 
way and I have no use for the Gpf 
calls, I don't much care. 

Gpf documentation is geared to¬ 
ward experienced programmers. Some 
of it seems to be lifted from the C ver¬ 
sion of the product, even* The docu¬ 
mentation contains no object reference, 
just a function reference, so you'll 
probably end up doing some digging 
to find out how to do a particular thing 
for a particular object* (It took me a 
long time to work out setting value set 
items, for example.) 

Gpf REXX has the worst develop¬ 
ment cycle of the three products. If you 
select save your file, Gpf will ask for 
verification. By default, if you try to 
close Gpf, Gpf will ask you if you re¬ 
ally want to exit. (It sticks this same 
over-prompting into your application, 
too.) 

Far worse than that, though, is 
Gpf s tendency to close windows* If 
you save your project, your windows 
close* If you run your project, not only 
do your windows close, your project 
closes and you must reopen it to con¬ 
tinue work. None of the three products 


offers the courtesy of a "recall" menu 
item, either, 

VX-REXX 



VX-REXX has, far and away, the best 
documentation of the three products* 
In all the time I have used it. I've 
found only a few vagaries in the docu¬ 
mentation, one of them (ironically 
enough) with the SetAttributes 
method that 1 had to use to set the 
items in the value set. 

But while it was difficult some¬ 
times to figure out how to perform 
some specific task in the other two 
products, that was rarely the case in 
VX-REXX (the above-mentioned 
SetAttributes method being the only 
case in this program). 

And just about anything is possi¬ 
ble under VX-REXX, too. You can cre¬ 
ate a new control at run time, some¬ 
thing not possible at all under Gpf 
REXX and something I could never fig¬ 
ure out whether it really was possible 
under VisPro/REXX. 

You can make your labels respond 
to double-clicks under VisPro/REXX, 
if that's what you want to do. The 
other products restrict you to the "nor¬ 
mal" events for objects* (It is possible 
to respond to my PM events from a 
Gpf app, but not easy to deviate from 
the normal.) 

At the same time, I actually un¬ 
covered a bug in the value set control 
while writing this program, which I 
hope has been corrected* (Setting a 
value set item to a null bitmap should 
have drawn the background color over 
anything that was already there, but 
that didn't happen in the right most 
column and bottom row!) 

As with Gpf REXX, VX-REXX re¬ 
quires you to cut and paste your rou¬ 
tines into a section editor. VX-REXX 
doesn't give you a really good way to 
plug these calls in, either. In some 
ways, VX-REXX's code integration is 
the weakest of the three* 


VISPRO/REXX 

The documentation for VisPro/REXX 
improved greatly between 1*0 and 2.0. 
I didn't really have much trouble fig¬ 
uring out how to do things using the 
new manuals. 

VisPro/REXX comes with a kind 
of automatic organization. Every pro¬ 
ject has a sub-proc folder where sub¬ 
routines are each kept as discrete files. 
The advantage to this approach over 
the other two is obvious: you can just 
drag your existing subroutine code 
into the sub-procs folder for any 
VPR application. Unfortunately, VPR 
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doesn't recognize HPFS long file¬ 
names, so your subroutines are re¬ 
stricted to eight characters. 

In addition, I found myself doing 
a lot of messaging back and forth be¬ 
tween the VisPro windows. In the 
Star Trek game, the LRS gets updated 
after certain events, and either of the 
other windows may want to call the 
LRSUpdate function. 

So, my initial thought is always: 
make it a sub-proc. The latest Vis- 
Pro/REXX, happily, has support for 
dragging-and-dropping code when 
creating sub-procs. Older versions re¬ 
quired you to manually insert code in 
sub-procs, which made them a less-at¬ 
tractive feature. 

The other, better option is to have 
the windows send messages to each 
other. I have the SRS and CP win¬ 
dows message the LRS when its time 
to update. But the support for mes¬ 
saging ends with "you can do it." 
VisPro/REXX doesn't give you any 
way of organizing your messages— 
which you will surely want for a pro¬ 
ject of any size. 


DECISIONS , DECISIONS 

It's very difficult for me to proclaim 


one product better than another, be¬ 
cause they are generally compatible 
products that excel or lack in certain 
areas, and all have peripheral ele¬ 
ments that make them more attractive 
(such as VisPro REXX's database dia¬ 
gramming tool). 

None of the products offers a par¬ 
ticularly good way to integrate exist¬ 
ing REXX code into the GUIs they 
build. This is unfortunate and has al¬ 
ways been a barrier to me personally 
developing really large programs 
using REXX. 

But what is likely to make or 
break a certain product for any indi¬ 
vidual is the user interface. And inter¬ 
faces are like programming languages 
or operating systems—it's difficult to 
predict what any person will like. 

I can't offer much in the way of 
metrics: For example, I could build 
the interface for the game in Gpf 
REXX in about half the time of the 
other tools, with VisPro REXX taking 
the longest—the opposite of what I 
would have guessed. You can't tell 
whether this reflects some personal 
bias or is a reflection of the smooth¬ 
ness of Gpf REXX vs. the raggedness 
of VisPro REXX—a raggedness that 


seems to have mostly been cured be¬ 
tween the 2.03 version I wrote the 
program with and the 2.11 that is cur¬ 
rently available, while Gpf REXX still 
languishes at 1.0. 

Actually coding a program in the 
three was basically the same in terms 
of time and effort. They each pleas¬ 
antly surprised me from time to time, 
and they each drove me up a tree 
quite often. If nothing else, this high¬ 
lights the dubiousness of proclaiming 
"a winner" among the three. 

When the products first came 
out, a lot of leapfrogging and compet¬ 
itiveness seemed to have died down 
in recent months. All three companies 
have products other than their REXX 
GUI builders, and 1 suspect they have 
been focusing on those of late. 

However, I expect to see a surge 
of new developments made to all 
three tools in the few months follow¬ 
ing the official availability of OO 
REXX. I hope so, because REXX still 
has a lot of untapped potential. 


Blake Watson is the author OS/2 Warp 
Programming for Dummies and and upcoming 
book on IBM Smalltalk. You can reach Blake 
electronically at 70303 t 373@CompuServe.com. 
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Communications 

REXX is ideal for e-mail applications. Vendor Independent Messaging (VIM) makes it 
possible. Here's an introduction to writing RexxVim applications. 

By MARK RAMSEY 



E-Mail Enabling REXX 


O ne of the most powerful features of 
REXX is support for external func¬ 
tions. Many application packages 
now support REXX through the use of REXX 
extension libraries. IBM LAN Server 4*0, for 
example, provides access to the full interface 
using REXX external functions. REXX li¬ 
braries are available to support everything 
from the dbase file system to a full commu¬ 
nications library. Because of its extensibility, 
REXX is an ideal development language for 
e-mail enabled applications. 

The Vendor Independent Messaging 
(VIM) specification, sponsored by Apple, 
Borland, IBM, Lotus, MCI, Novell, Oracle, 
and WordPerfect, defines a nonproprietary, 
multiplatform solution for providing mes¬ 
saging services within applications. VIM al¬ 
lows a single interface to be used across sev¬ 
eral e-mail products, such as IBM UltiMail, 
Lotus Notes, Lotus cc:Mail, or Netware 
MHS. VIM support is available on many op¬ 
erating system platforms, such as DOS, 
Windows, OS/2, Macintosh, Netware NLM, 
and UNIX. 

Lotus offers the VIM Developer's 
Toolkit to support VIM application develop¬ 
ment using C/C++ or Visual Basic. 
Innovative Business Technologies offers 
REXXVIM to support VIM development 
using OS/2 REXX. The rest of our focus will 
be in the REXX environment; however, the 
APIs are the same in all of the environments* 

DEFINING THE E-MAIL APPLICA TION 

Our application will be a system monitoring 
agent. The agent will run on remote OS/2 
systems to prevent "out of disk space" prob¬ 
lems. The users on the remote systems all ac¬ 
cess our company e-mail system, which will 
be the pathway for our agent to send warn¬ 
ing messages. 

In our example scenario, it is important 


to note that all of the remote systems do not 
need to be using the same e-mail package. 
As long as all of the connections are in place 
for each of the mail systems to exchange 
mail, the individual packages are not impor¬ 
tant. Some of the systems may be using 
Lotus Notes within a departmental environ¬ 
ment, while others may be using cc:Mail as 
the mail service* 

For our discussion, all of the remote sys¬ 
tems must use an e-mail system that sup¬ 
ports VIM* It is possible to use VIM with sys¬ 
tems that support the Microsoft MAPI mail 
API, but we will leave that to a future article* 

Because of the flexibility of sending 
warning messages through the e-mail infra¬ 
structure, the remote systems do not need to 
be connected to a common network* This al¬ 
lows our application to send warning mes¬ 
sages from systems that are on many differ¬ 
ent networks, as long as those systems can 
send e-mail to the main system. Because of e- 
mail gateways and bridges, our application 
will be able to monitor remote systems that 
connect to a service provider to route mes¬ 
sages to the main company location. 

Our example monitoring agent will be 
limited to tracking remaining disk space* If 
the remaining disk space on a remote system 
falls below 5%, the agent will send a warning 
message to the Administrator ID, The basic 
monitor application can easily be expanded 
to track other components on the remote sys¬ 
tem or even problems on remote servers. 

BUILDING OUR APPLICATION 

The first step in our application is loading 
the external function library for VIM sup¬ 
port. The code fragment shown in Figure 1 
loads all of the functions in the REXXVIM li¬ 
brary. The ftxFundldd statement is used to load 
the RiVIMLoadFuncs external function* Calling 
the function loads the rest of the functions in 
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Figure 1 . Loading the VIM extensions. 



Figure 2. Determining available disk space using SysDrivelnfo. 



Figure 3. Opening and logging into a session using the VIM interface. 


the library. If the RxFuncAdd statement 
fails, our application will go immedi¬ 
ately to the cleanup code. 


For our application, we could also 
choose to load only the nine functions 
that are needed. These functions 


would be loaded through nine individ¬ 
ual RxFuncAdd calls. With this approach, 
the cleanup phase would also require 
nine calls to the RxFuncDrop function to 
release the individual VIM functions. 

MONITORING DISK SPACE 

In our application, the monitoring 
agent will send a warning message 
when available disk space falls below 
5%. Using the SysDrivelnfo function 
provided with the REXXUtil library, we 
are able to obtain drive size and avail¬ 
able disk space. The code fragment 
shown in Figure 2 calculates the per¬ 
centage of available disk space. Our 
application can use this figure to deter¬ 
mine if it is time to send a warning 
message. 

If the available percentage reaches 
5% or less, our application must send a 
warning message. The code fragment 
shows the application creating the 
message text to send to the administra¬ 
tor and creating a file listing of the root 
directory. Let's look at the steps in¬ 
volved in sending the message once 
the threshold has been met. 

Initializing VIM. Once all of the nec¬ 
essary functions are loaded into the 
REXX environment, we must initialize 
the VIM subsystem. The following 
must be the first VIM call made: 

rc = RxVIMInitializeO 

With the initialize, like all of the 
VIM calls, a zero return code indicates 
success. The RxVINInitialize function 
will return a nonzero return code only 
if a problem exists with the underlying 
mail system. 

Opening A Session. The next step in 
our application is establishing a ses¬ 
sion with the actual e-mail system. The 
RxVINOpenSession function opens and 
logs into a session using the VIM inter¬ 
face (Figure 3). 

The call is comprised of three 
parts: database path, user name, and 
password. The database path is the lo¬ 
cation of the e-mail file containing 
message information. In Lotus cc:Mail, 
this would be the location of the HLAN- 
DATA and CLANDATA files. In Lotus Notes, 
this would be the location of the mail 
database file. The name and password 
parameters must be for a valid user on 
the e-mail system. 

For our application, each remote 
system will use the name of the user 
on that system. VIM supports multiple 
connections using the same user name, 
so our program will not interfere with 
normal e-mail functions. The remote 
users can continue to use whatever e- 
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mail access product is currently in 
place, while our application runs in the 
background. 

The RxVIMOpenSession function re¬ 
turns the value of the session in the 
REXX variable Session. This variable 
contains a pointer to the session 
opened by the function. We will use 
this variable in future VIM calls. The 
session variable allows our applica¬ 
tions to have multiple sessions opened 
with VIM from different concurrent 
REXX applications. 

Creating the Mail Message. We are 
now ready to create the actual warning 
message. First, we must create a new 
message shell using the RxVIMCreate- 
Hessage function. The function requires 
the session pointer, which was re¬ 
turned from our RxVIMOpenSession call, 
and the message type to create. The 
current implementation of VIM sup¬ 
ports only mail message types, so the 
type will always be VIM.MAIL. The func¬ 
tion will return a message pointer for 
us to use with other message func¬ 
tions. We will use the variable 
Message to contain the value of the 
message pointer. 

Once the message shell is created, 
we are ready to compose the warning 
message. Our first action will be to 
specify the message header informa¬ 
tion. The RxVIMSetMessageHeader function 
will be used to set the subject and pri¬ 
ority of the message. Figure 4 shows 
the code fragment to create the mes¬ 
sage shell, set the subject of our mes¬ 
sage to "Disk Space at X percent," and 
set the priority to high. The 
RxVIMSetMessageHeader function is called 
once to set each attribute. 

All of the VIM functions use key¬ 
words to specify and return values. 
This allows the same application to 
run on multiple platforms without the 
need to address precision. The key¬ 
words allow programs to ignore the 
actual values and focus on the function 
itself. The two keywords used in the 
RxVIMSetMessageHeader are VIMSEL.SUBJECT 
and VIMSEL.PRIORITY for subject and pri¬ 
ority, respectfully. 

Next, we will set the recipient of 
our message using the RxVIMSetRecipient 
function. This call allows us to address 
the message to the Administrator ID 
and even send a copy to another ID if 
necessary. For our application, we will 
send the warning message to an ID 
called System.Monitor. This call, as you 
can see in Figure 5, also uses the 
Message pointer variable from the 
open session call. 

In our application, the System 
Monitor ID will be defined on all of the 



Figure 4. Creating a shell message and setting the message header information. 



Figure 5. This call uses the message pointer variable from the open session call. 





remote post offices. This will allow us 
to specify the ID only in the 
RxVIMSetRecipient function. The function 
provides the flexibility to specify the 
full name and address of the recipient if 
it is not included in the local post office. 

The last part of our message cre¬ 


ation is adding text to the message to 
provide the administrator some addi¬ 
tional information. In the code frag¬ 
ment shown in Figure 6, we provide 
the drive size, free space, and drive 
label. All of these items are returned 
by the call to SysDrivelnfo. 
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Figure 6. The drive size, free space, and drive label is provided 


The second call to RxSetMessageltem 
attaches the DIRLISLtxt file to our mes¬ 
sage. The file is a listing of the root di¬ 
rectory on the remote system. If we 
change the directory command to in¬ 
clude subdirectories, the file attach¬ 
ment would be a directory of the entire 
disk drive. The system administrator 
can use this information to assist the 
remote user in system cleanup. 

Sending the Maif Message , Now 
that the message is complete, we are 
ready to send it on its way* The RxVIH- 
SendHessage submits the message to the 
e-mail system, using the Message 
pointer: 

rc “ Rx¥MSendMessage( Message } 

Once the message is sent, the e- 
mail system takes control of routing 
the message to its destination. All mes¬ 
sage resources are released, and the 
message pointer is no longer valid. 

Cleaning up. After we have fin¬ 
ished sending our message, we must 
close the active session and end our 
VIM connection for this process. The 
RxYIHQoseSession closes the active VIM 
session and frees all of the VIM session 
resources. The function uses the ses¬ 
sion variable to close a specific session. 


The Rx VIM Terminate function ends 
the VIM connection for the process. 
This function is the counterpart to the 
RxVIMInitialize function. It is part of the 
overall VIN cleanup process. 

Upon exiting our application, we 
should make a call to RxVIMDropFuncs* 
This function releases all of the VIM 
functions from the REXX environment. 
Failing to make this call will cause the 
RxFuncAdd call to fail for future execu¬ 
tions of our application. 

Hey r What's Wrong? Error Pro¬ 
cessing, If any of the VIM functions 
complete with a nonzero return code, 
the VIM specification provides a func¬ 
tion to determine the cause of the fail¬ 
ure. In our application, a nonzero re¬ 
turn code will cause a jump to the 
VIMError procedure. The VlHError proce¬ 
dure calls the VIHStatusText function to 
obtain additional information regard¬ 
ing the failure. 

SUMMARY 

Now that we have a fully functional e- 
mail enabled REXX application, our 
system monitor can be expanded to 
perform many other functions* The ap¬ 
plication could monitor network errors 
and forward the error log to a network 
administrator. A similar application 


could forward a status message daily 
regarding the performance, audits, 
print jobs, and so on from a remote 
server. Our example application is 
just the beginning in the world of 
REXX e-mail* 


Mark Ramsey founded Innovative Business 
Technologies Inc . (IBT) in 1983. He has been 
actively involved with OS/2 consulting and 
development since 1987. Ramsey has a degree 
in computer science and business administra¬ 
tion from Capita / University. IBT offers several 
REXX development tools t including the 
REXXVIM toolkit described in this article. Mark 
can be reached on CompuServe at 74583 ; 1530 
or at 1614) 791-9055 Ext. I t 
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Control of OS/2's Workplace Shell is easy, thanks to REXXUtil. Here's object-oriented 
programming you can do today. 

By GOWRISANKAR SIVAPRASAD 


S' 



Intro to Workplace 
Shell Programming 
Using REXX 


r he OS/2 Workplace Shell (WPS) 
provides interfaces to program¬ 
mers that can be used to manipu¬ 
late the objects in the Workplace Shell desk¬ 
top (hereafter referred to simply as the 
desktop). For REXX programmers, this 
comes in the form of the REXXUtil DLL. 

REXXUtil is a dynamic link library that 
provides a set of functions to manipulate 
the WPS objects. This DLL requires OS/2 
2.x or above with OS/2 REXX installed. I 
will discuss how to use the REXXUtil func¬ 
tions in Workplace Shell programming. 

To use these functions, first the 
REXXUtil library must be loaded. The built- 
in function R* Font Add can be used for this, as 
shown here: 

call RxFuncAdd "SysLoadFuncs", ■REXXUtil", 
"SysLoadFunes" 

This loads the complete REXXUtil li¬ 
brary, making all the functions in the li¬ 
brary usable by all OS/2 sessions. 

If the services of just one function is re¬ 
quired, then we can load that function, as in 

call RxFuncAdd "SysCreateObject" » "REnUtil", 
"SysCreateObject" 

This just loads the SysCreateObject func¬ 
tion in the REXXUtil library. 

Later, I will introduce the different 
WPS objects and how to create, destroy, and 
update different kinds of objects. Toward 
the end of this article, references to some 
freeware and shareware utilities for manip¬ 
ulating WPS objects are given. 

INTRODUCTION TO WPS OBJECTS 

The OS/2 Workplace Shell provides many 
different types of objects. The most com¬ 


mon ones are the Desktop, Folder, Program, 
Shadow, and Datafile objects. The Folder 
object is a placeholder to store other objects. 
Program files are a shortcut to execute pro¬ 
grams. Executables can be associated with 
Program objects and get executed when 
users double-click on the Program object's 
icon. The Shadow object provides a mecha¬ 
nism to duplicate an object at another loca¬ 
tion, with the same settings. The shadow 
object behaves in the same way as the origi¬ 
nal It gets deleted when the original object 
is deleted. Any number of shadows can be 
created for a given object. 

Each object in the system belongs to a 
particular class. Folder objects belong to 
class WPFolder. Each class is given a 
unique name. A class has to be registered 
before any objects belonging to that class 
can be created. 

The REXXUtil package contains a 
SysQueryClassList function that retrieves 
all the registered classes in the system. 


Syntax : call SysQueryClassList stem 
Parameters : stem the name of the stem 
variable to hold the list of all 


class 

10 is 

UP Object PHUP 

class 

11 is 

WPSysteni yPCONFIG 

class 

12 is 

WPFileSystem PHVP 

class 

13 is 

UPOataFile PKtfP 

class 

14 is 

yPProgramFile PMP 

class 

IS is 

WPFolder PHYP 

class 

16 is 

y PD rives Pm P 

class 

17 is 

WPShredder PWWP 

class 

18 is 

ttPDisk PHVP 


Figure f. Common object classes. 
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dassname = "HPFolder" 
title = n HyDunFolder" 
location - ,, <WP_DESKTOP>" 
setup-string = 

M OBJ E€TID=<KY _ 0 W Jl_F 0 L DEft>; ICONP A R 
myoynfolder.ico;" 


from then on. A new class is imple¬ 
mented as a DLL and registered as 
shown here 

rc=Sy sftegiste rObj ectCLa s s (" H y New da $s", 
"WyNeuOassDLL"} 


rc - 

Sy sC reateO bj ect (cla s sname, title location, 
setup-string) 
if rc * 1 then 

say " HyOwnFolder : Created 11 

else 

say " Problem in creating 
HyOunFolder. rc ® " rc 


Figure 2. Create anew folder object. 


registered classes in the system 
Example : call SysQueryCLassList 
"allclasses. 11 

*/ 

do i = 1 to allclasses,O 
say "class " i " is " allclasses.i 

end 

Figure 1 shows an example output 
from this piece of code. 

REGISTERING/DEREGISTERING A CLASS 

The functions SysRegisterObjectCLass and 
SysDeRegisterObjectQass can be used to 
register and deregister an object class. 
Registering a class makes it part of the 
system (until it is deregistered), and 
objects of that class can be created 


The first parameter is the name- of 
the class, and the second parameter is 
the name of the module that contains 
the class implementation. The function 
returns 1 (true) if the class was regis¬ 
tered and 0 (false), otherwise. 
Similarly, 

rc=SysOeregistGrObjectClass( M NyNeuClass") 
deregisters an object class. 

CREATING A NEW OBJECT 

Instantiation of an object class is called 
simply "creating a new object." A new 
object has associated with it the class it 
belongs to, title, location, and a set of 
parameter settings defining the behav¬ 
ior of that object. 

Here's how the function Sys- 
CreateObject can be used to create a 
new object. 

Syntax:rc= Sy5Create0bject(classname, 
title, location <,setup-string>) 

The parameters of this function 
are as follows: 

■ Classname: The name of the (regis- 


OBJECT-ID 


Object-id is a unique string assigned to a WPS object that can be used 
to identify it. Some predefined object-ids of system folders include the 

following. 

Object ID 

Description 

<WP_DESKTOP> 

The Desktop 

<WP_START> 

The Startup Folder 

<WP_0S2SYS> 

The System Folder 

<WP_TEMPS> 

The Templates Folder 

<WP_C0NFIG> 

The System Setup Folder 

<WPJNF0> 

The Information Folder 

<WP„DRIVES> 

The Drives Folder 

<WP_NOWHERE> 

The Hidden Folder 



Figure 3 Create a new program object 

tered) class the object belongs to. 

* Title: The name (title) you want to 
give to the object. 

* Location: The place where you want 
the object to be created. The place 
can be the desktop or in a folder. 
The parameter should be the object 
Id (See sidebar on Object Ids for ex¬ 
planation) of the location or a fully 
qualified filename. The location can 
be either the Desktop or a folder. 

* Setup-string (optional): See "Setup 
String" for a detailed explanation. 
Some information available in docu¬ 
ments in STP sites has been used 
here, 

* The function returns 1 (true) if the 
object was successfully created or 0 
(false) otherwise. 

Figure 2 uses sample code to cre¬ 
ate a new folder object. 

The code in Figure 2 creates a 
folder called HyOunFolder and places it 
on the desktop. The location can be 
changed to any other folder by giving 
the respective object ID. The object ID 
of this folder is <HV_DWN_FDLDER>. This ob¬ 
ject ID is used to create other objects 
within this folder. 

After this is executed, we can see 
this folder on the desktop with the my- 
ownfolder.ico icon. Currently, it is an 
empty folder. We will add some ob¬ 
jects to this folder next. 

Note that we can change the ob¬ 
ject settings for this folder from its 
Settings notebook. 

The code in Figure 3 creates a new 
program object called HyProgram_in_My- 
QunFolder and places it in the HyOwnFolder 
we created in the previous example. In 
the setup-string, we have specified the 
program executable name(mypro- 


t4 


ft E XX REPORT 












classnafne * "WPShadoa” 

title ■ h H^Shadou_iJV_NyQwnFold@r M 

location = "<HY_Ok«_FDLDER>" 

setup-string = n SH 1,00 WI0=< HP_EPK> " 
rc * 

Sy sCr eat eObj ect{ cla ssnauve, title, location, 
setup-string) 
if rc * 1 then 

say M HyShadow : Created' 1 

else 

say " Problem in creating 
RyShadov. rc * ” rc 


Figure 4. Create shadow objects. 

gram.exe) that will run in full-screen 
mode with the file mydata.dat as a pa¬ 
rameter. The object is represented by 
the myprogramdco icon inside the 
folder. 

If you are considering placing an 
object in the Startup Folder (<VP_START- 
UP>), make it a shadow of the object. 

This piece of code in Figure 4 cre¬ 
ates a shadow of the OS/2 EPM editor 
object inside the folder MT_OWN_FOLDER. 
Note that the classname is given as 
VPShadou, and in the setup string we 
have just given the object-id of the 
EPM editor. To create a shadow of 
any object in the desktop (through a 
program), it is necessary to know its 
object-id. 

DESTROYING AN OBJECT 

Any existing desktop object can be 
destroyed using the following 
SysDestroyObject function* 

Syntax : rc = SysDestroyObject(name) 

Pa rasters: 

Name: The name of the object to be 
destroyed* This can be specified object-id 
or as a fully qualified filename. 

Returns:! (true) if the object was suc¬ 
cessfully destroyed or 0 (false) other¬ 
wise. 

The following code destroys the 
MyProgram object we created in 
Figure 3* 

if 5ysDe£tr0yGbject( ll <HY_PROGRAM> 11 ) then 
say "HY.PROGRAH destroyed successfully” 
else 

say “NY.PROGRAM was not destroyed” 

Note that we have used the object- 
id <HY_PROGRAH> to specify the program 
object* This function destroys the ob¬ 
ject from the desktop only; it does 


SETUP-STRING 


The setup-string field used in the SysCreateObject and the 
SysSetObjectData functions is a set of "keyname=value" pairs 
separated by semicolons. It defines the behavior of the object. Each 
object class is expected to document the keynames and associated 
values that it accepts. 

All parameters have safe defaults, so we need not pass any parameter 
unnecessarily. Also, it shields programmers from knowing all the key¬ 
names for an object. Setup string keynames correspond to the settings 
that can be accessed from the object's Settings notebook pages. 

The following are some important setup string parameters for some 
commonly used WPS objects. 

For WPFolder Class 


KEYNAME 

VALUE 

PURPOSE 

ICONFILE 

filename 

Sets the object's icon 

IC0NRES0URCE 

id.moduie 

Sets the object's icon "id" 
refers to the icon resource in 
the "module" DLL. 

MINWIN 

HIDE 

Hide the views when object 
is minimized 


VIEWER 

Minimize to the minimized 
window viewer 


DESKTOP 

Minimize to the desktop 

ICONVIEW 

FLOWED 

The objects inside the folder 
are shown using the 

FLOWED icon view 


N0NFL0WED 

Shown using the NON 
FLOWED icon view 


NOLINES 

Shown using nongrid icon 
view. 

For WPProgram Class 


KEYNAME 

VALUE 

PURPOSE 

EXENAME 

filename 

The program to execute 

PARAMETER 

1 TW !Imi 1 1 

parameters 

Parameters to pass to 

illiji 


program 

STARTUPS 

pathname 

Working directory for the 
program 

PROGTYPE 

FULLSCREEN 

Run program in OS/2 
full screen mode 


VDM 

Run program in DOS 
full screen mode 


WIN 

Run program in Win-OS/2 
full screen mode 


PM 

Run program in PM mode 


WINDOWEDWIN Run program in Win-OS/2 
Window mode 


WINDOWABLEVIO 

Run program in OS/2 

Window mode 

MAXIMIZED 

YES 

Start program maximized 

MINIMIZED 

YES 

Start program minimized 
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I nothing to the actual files. The object 
I does not exist in the HyQwnFolder any- 
fgH more. 

CHANGING OBJECT SETTINGS 

After any object has been created, the 
object's settings (or the setup data as¬ 
sociated with the object) can be 
changed (or new setup data added) 
using the SysSetQbjectData function: 

Syntax:rc*SysSetObjoctData(name,setup¬ 
string) 

The parameters of this function are: 

* Name: The name of the object to be 
destroyed. This can be specified ob¬ 
ject-id or as a fully qualified file¬ 
name, 

* Setup-string: A setup-string similar 
to the one we used in the 
SysCroatoObject function. 

The function returns 1 (true) if the 
object data was successfully updated 
or 0 (false) otherwise. 

Let's say we would now like to as¬ 
sociate another icon (mynewicon.ico) 
with the My Program object we created 
in Figure 3, The following code does 
exactly that: 

if SysSetObjectData ("<HY„PRQGRAM> 11 „ "ICON 


PARAH^mynewlcon .Xco 11 ) then 

say "HyProgram setup data updated suc¬ 
cessfully" 
else 

say "HyProgram setup data was NOT 
updated" 

When this code is executed, we 
can visually see that the icon repre¬ 
senting the object gets changed to the 
mynewiconieo icon. In a similar fash¬ 
ion, any setup data can be updated (or 
added) to any existing object, 

UTILITIES FOR MANIPULATING 
WPS OBJECTS 

Many utilities exist as freeware or 
shareware to ease the job of manipu¬ 
lating WPS objects. These utilities 
(and many more) are available on the 
Hobbes CD-ROM or by anonymous 
FTP at ftp.cdrom,com or ftp- 
os2.nmsu.edu. 

• WPSGEN, BUILDSOM: These two 
programs can be used to create WPS 
objects from a script file. 

• MNREXX: This program creates a 
new WPS class that gives access to 
WPS objects in REXX. It has other 
uses, too, 

• WPS Class List: This program comes 
as part of IBM OS/2 Developer's 
Toolkit 2.lit is a WPS class browser 


and can be used to create instances 
of the WPS classes (an interactive 
way of creating WPS objects). 

CONCLUSION 

You can programmatically manipulate 
workplace shell objects from REXX 
using the functions described here. 
Applications can use this simple 
method to extend their functionality to 
manipulate WPS objects. You can use 
this to create applications with rich 
functionality because it lets you create, 
destroy, or update desktop objects. 

Information on WPS program¬ 
ming using REXX is available in the 
REXX Reference document supplied 
with OS/2, as part of various WPS 
utilities, and as separate documenta¬ 
tion in many OS/2 FTP sites. (See in¬ 
dexes at the respective FTP sites for a 
complete list.) 


Gowri Sankar Siuaprasatf is a graduate stu¬ 
dent in the Department of Computer Science 
and a research assistant in the Department of 
Economics at Iowa State University .: He works 
on OS/2 and UNIX software development and 
does research in specification languages for 
object-oriented distributed systems. He can be 
reached via internet at $ivapras@cs. iastate.edu. 
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Printing 

REXX and PostScript complement each other. PostScript adds printer formatting, 
graphics and fonts, and can be easily used from a REXX program. The author of REXX 
Cookbook shows us how. 

By MERRILL CALLAWAY 


Combining REXX 
and PostScript 


EXX and PostScript are interpreted 
script languages, complementing 
each other to a remarkable degree. 
REXX can construct command strings as 
well as read and write files, but it cannot 
perform complex page formatting. 
PostScript is a page description language 
capable of complex formats, graphics, and 
fonts, however, it is clumsy at accessing 
system resources. This is because the 
PostScript interpreter resides in the printer 
and is incapable of responding to a com¬ 
mand line interface through the usual paral¬ 
lel port printer connection. By using the 
strengths of each language, it is possible to 
code some very useful REXX/PostScript 
programs for printing to a PostScript 
printer. 

It is simple for a REXX macro to con¬ 
struct and write PostScript command 
strings directly to the parallel port object or 
to a print file. As long as PostScript files or 
strings are written to the logical parallel 
port (LPT1, LPT2, and so on) to which the 
OS/2 install program has assigned the 
PostScript driver, these strings will be inter¬ 
preted as PostScript commands. 

For example, if a Lexmark Optra R 
laser printer has been installed both with a 
PCL5 driver assigned to LPT1 and 
PostScript to LPT2, the program should 
write PostScript to LPT2. PostScript print 
files will export to other platforms or to im¬ 
agesetters for printing. By removing only 
one line from a PostScript print file, the op¬ 
erator showpage (use a text editor), you may 
then use the file as a "background" page. A 
REXX program may now append text 
and/or graphics in PostScript format. A 
final showpage appended to the end of this 
composite file makes it print the back¬ 
ground in addition to the added 
text/graphics. 


HOW DOES POSTSCRIPT WORK? 

Like REXX, PostScript uses an interpreter, 
but it resides inside the printer usually in 
an EPROM. Just like CMD.EXE, the 
PostScript interpreter waits for an instruc¬ 
tion it recognizes and then executes it. 
When a file is copied or REXX writes one 
line at a time to LPT1, the PostScript inter¬ 
preter at the other end of the parallel cable 
attempts to execute the lines of text as 
PostScript commands. 

PostScript uses a stack in the printer's 
RAM for holding objects and operators 
arranged in last in, first out (LIFO) order. 
PostScript is a combination of postfix and 
script. In postfix computing, the operand 
(the data object) is specified (pushed onto 
the LIFO stack) before the operator. The 
PostScript interpreter places objects (includ¬ 
ing operators) on the stack in the order that 
it receives them. An operator takes the lat¬ 
est object(s) off the stack and performs a 
specified operation. An operator might call 
for the last four data objects on the stack or 
may need only the latest single object. 

All PostScript language objects are 
ASCII strings and, therefore, easy to con¬ 
struct with REXX. In PostScript, objects can 
be dictionaries of fonts, definitions of func¬ 
tions, numbers, operators, or literal strings. 
Literal strings are enclosed in parentheses, 
which are special characters. The back slash 
(\) is another special character. If a paren¬ 
thesis or a back slash is to be included as 
part of a literal string, it must be escaped by 
prefixing it with a back slash. A PostScript 
program to print the string roast beast looks 
like this: 

/Courier findfont 10 scalefont setfont 
(roast beast) 

72 720 moveto show 
showpage 
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/* PE.CMD Envelope PS Printer */ 

/* NOTE: Change the following value to match your type of 
♦♦ printer. If envelope is center fed; e.g. Epson EPL-7500, 

♦* then change to center-1. Lexmark Optra R is side feed. 

♦* Side feed envelopes have different x and y values. 

** Different values are accounted for in xadd and yadd. 

♦/ 

center^) 

IF centers THEN DO 

/* Center feed envelopes. */ 
xadd«0 
yadd=0 
END 

ELSE DO 

/* Optra R side feed envelopes. */ 

/* Different side feed printers may need different values. */ 
/* Print full sheet of paper first to verify dimensions. */ 
xadd * -108 
yadd = 158 
END 
START: 
drop match 
print*'no' 
savefile®" 

/♦ 

** NOTE: Change the following database file 
** to a filespec of your choosing. 

** The format of the file uses '|' as a separator. 

** Each line begins with '|' and 'I' separates each 
** line of the address. The address keyword is 
** the first entry. Example: 

♦* |keyword|linel|line2|line3|line4| 

♦* There may be as many lines as necessary, but each 
** one must be separated by 'I'. 

*f 

addrfile*'C:\REn\ADDRENV\ADDFILE.TJ(T' 

SAY 'Enter address keyword, OR [Enter] for new address.', 
'Q®Quit. L*List Addresses.' 

PARSE UPPER PULL input 
IF input ** 'Q' THEN EXIT 0 
IF input ** 'L' THEN DO 

DO i=l WHILE LINES(addrfile) \* 0 
line.i*LINEIN(addrf ile) 

PARSE VAR line.i '|' name.i . 

SAY name.i 

/* OS/2 Command Window only holds 23 lines...*/ 

IF i//23*0 THEN DO 
SAY , 

'23 lines visible. Press [Enter] to see next 23 lines.' 
PULL . 

END 

END 

CALL STREAM addrfile, 'C', 'CLOSE' 

SIGNAL START 
END 

SIGNAL ON HALT 
IF input « " THEN DO 

SAY 'Enter address: line 1 [Enter], line 2 [Enter], etc.' 

SAY 'Enter [Ctrl-C] AFTER last [Enter] to stop.' 

DO m=l 

PARSE PULL add.m 
END m 

END /* input®*"*/ 

IF input \* " THEN DO 
IF LINES(addrfile) THEN DO 
DO i-1 WHILE UNES(addrfile) 


Figure 1 . PE.CMD REXX/PostScript Print Envelope Utility (continued on page 19). 


If the above were saved to a file, 
you could copy it to LPT1 and it 
would print the string roast beast in 
Courier font, 10-pt size, and at the top 
of the page with 1-inch top and left 
margins. The PostScript interpreter 
puts /Courier on the stack (a / causes 
PostScript to interpret a string as the 
name for an internal object). The oper¬ 
ator findfont finds the Courier font in¬ 
side the printer's memory of resident 
fonts. A number 10 is pushed on the 
stack, and a scalefont operator takes 
the two operands-the result of find- 
font and the scale number-and scales 
the entire font. The operator setfont 
sets up the font dictionary using the 
information from the stack (the scaled 
font) for our program to use. The ac¬ 
tual PostScript object now on the 
stack is really an address pointer to 
what is called an encoding vector, 
which is itself a lookup table of codes 
and corresponding printable charac¬ 
ters. By means of this encoding vec¬ 
tor, PostScript automatically builds 
each character internally in software 
when setfont is interpreted. 

The parentheses tell PostScript 
that the next line is a literal string, so 
it pushes it onto the stack (on top of 
the font dictionary of 10-pt Courier). 
Note that pushing onto the stack is 
equivalent to writing a string to the 
parallel port since the PostScript in¬ 
terpreter is waiting at the other end. 

On top of the font and the literal 
string, the PostScript interpreter now 
pushes the X coordinate measured in 
points (there are 72 points in an inch), 
72, followed by the Y coordinate, 720. 
Points are units of measure persisting 
from the age of printing with lead 
type. PostScript measures its coordi¬ 
nates from an origin (0,0) that begins 
at the lower left corner of the paper 
and moves up in the Y direction and 
to the right in the X direction. The co¬ 
ordinates represent the upper left 
hand of a letter-size paper with top 
and left margins of one inch. This is 
where the string literal will print. 

The operators, noveto and show, are 
pushed onto the stack. Noveto moves to 
the current point on the page deter¬ 
mined by the two underlying X,Y co¬ 
ordinates on the stack. Show commits 
to print the text underlying it at the 
current point on the page. No text is 
actually printed, however, until show- 
page. Think of an invisible cursor mov¬ 
ing around the page according to the 
moveto operators. The show operator 
commits to text placement at each 
new location. After everything is com¬ 
plete (the font, the text, and where it 
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goes), the last PostScript operator, 
shoupage, prints the page as it was de¬ 
scribed. The showpage operator is al¬ 
ways the last PostScript operator on a 
page. 

CUSTOM FORMS 

By using PostScript, it is possible to 
make a REXX program that custom 
prints complex forms! The technique 
is simple. In a DTP or word processor, 
lay out the blank form. Print a copy.. 
Also, save the PostScript print file. 
Edit the print file and remove only the 
line showpage near its end. Write a 
REXX macro to obtain user input 
data. 

With a millimeter ruler, measure 
the X,Y coordinates for placement of 
each line of this data text within the 
blank form. Multiply millimeter mea¬ 
surements by 2.83465 to obtain points. 
Use REXX to construct an appropriate 
PostScript print file like the previous 
example, placing the user data within 
the form. In the same REXX program, 
copy the blank form print file (minus 
showpage) to the logical port assigned to 
PostScript (LPT1 and so on), followed 
by the REXX-constructed, data-print¬ 
ing PostScript code. The single, final 
showpage (from the REXX program) 
will print the whole page, complete 
with data. Using VX-REXX, a user- 
friendly interface could be developed 
and the most complex custom forms 
printed with very little programming 
overhead. Now for some specific 
REXX/PScode. 

PRINTING ENVELOPES 

It takes far too long to load a DTP or 
word processor program just to print 
one envelope. This calls for a REXX 
and PostScript envelope print utility, 
which runs quickly from the OS/2 
Window. It not only prints envelopes 
but also keeps a simple and efficient 
database of addresses too. 

Users can copy an address from 
an open document directly into the 
OS/2 Window via the clipboard. This 
utility is quicker to use than a DTP or 
word processor program, even when 
they are open. After a few addresses 
are saved in the database, the most 
frequently used addresses will be just 
two or three keystrokes away. 

PE.CMD works with either a center- 
feed printer (such as the Epson EPL- 
7500) or a to-one-side envelope-feed¬ 
ing printer (Lexmark Optra R). It is 
easily adapted to work with any 
PostScript printer capable of feeding 
standard No. 10 business-size en¬ 
velopes of 9 V 2 x 4 V 8 inches (you 



Figure 1 . PE.CMD REXX/PostScript Print Envelope Utility (continued on page 20}. 
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Figure 1 . PE.CMD REXX/PostScript Print Envelope Utility (continued from page 19). 


may alter the code for a different size 
envelope or multiple choices for en¬ 
velopes). Figure lisa listing of PE. CMD. 

PROGRAM DESIGN 

The program is in three sections. First, 
it maintains the address database file 
and allows the user to enter new ad¬ 
dresses or call up frequently used ad¬ 
dresses by entering a keyword. The 
database file uses a separator charac¬ 
ter to begin and end each line of the 
address. I used a pipe symbol. The 
keyword for the address is a 
mnemonic string and may be input to 
recall an entire address. Each database 
entry begins with the keyword for the 
address, and the address takes up ex¬ 
actly one line in the database file. 


Printers feed envelopes through 
in at least two ways: centered and to 
one side. If the printer feeds en¬ 
velopes at the center of the paper tray, 
then code center=l, and xadd-0; 
yadd=0, In this listing, Center=0 and 
xadd, yadd are set for No. 10 business 
envelopes feeding into a Lexmark 
Optra R. It feeds envelopes at the 
right side of the paper path from the 
rear input tray. Optra R users should 
also turn off the AES program. Auto 
software selection is not needed for 
directly copying PostScript to LPT2. 

The repeatable section labeled 
START: allows data entry, recall of an 
address previously saved, or viewing 
of the address keyword list. In case a 
fresh address is entered line by line. 


Ctrl+C is used to signal HALT to escape 
data entry mode. 

The final section is a PROCE- 
DURE-labeled printaddress, which the 
program calls when it needs to print 
the address on an envelope. Note the 
list of exposed variables. There are 
many similarities between this inter¬ 
nal function and the short sample 
PostScript program. Note the use of 
REXX expressions and tokens to build 
up the lines of PostScript data and op¬ 
erators. To view the PostScript output 
of this program, comment out one 
line, par='LPT2' and substitute 
par=<fHespec>, Figure 2 shows a typical 
print output file. 

REENCODtNG A VECTOR 

The program reencodes the character 
table to the ISOLatinl vector. This 
makes a different encoding vector for 
characters in the chosen font, 
NewCenturySchlbk. The new encod¬ 
ing enables printing of accented char¬ 
acters. The normal characters are un¬ 
affected, so if you have no German 
addressees, you will never notice this 
feature. The reencoding PostScript in¬ 
structions do the following: 

/NewCenturySchlbk^Roman findfont 

dup length diet begin 

{1 index /FID nefdefHpop pop}ifelse}foraTL 

1. Find the font and make a copy of 
the font dictionary. Copy all entries 
{def> except those equal to font ID 
/FID; ne means not equal to; pop 
means to raise the stack and dis¬ 
card the top item; ifelse and forall 
are loop control, and 1 index is the 
iteration specifier. The brackets ({}) 
organize the grouping of items. 

/Encoding ISOlatinlEncoding def 

currentdict 

end 

2. Replace the font's Adobe 
StandardEncoding vector with the 
ISOLatinl Encoding vector, which 
places accented characters in con¬ 
trol character positions (which are 
not normally used by fonts). ISO¬ 
Latinl Encoding is a built-in 256-el¬ 
ement array of character names de¬ 
fined in the PostScript system diet, a 
part of the interpreter. 

/NewCenturySchlbk-ISQLatinl exch 
definefont pop 

3. Give the new font a different name 
to reflect the fact that it is reen¬ 
coded with ISOLatinlEncoding. 


20 


R E X X REPORT 











Figure 2. PostScript Output from PE, CMD 

Now that the new font is defined, 
the program can find it, scale it, 
and set it as usual. PostScript 
Language Reference Manual, page 
275f and Appendix E provides 
more on encoding vectors. 

LANDSCAPE PRINTING 

It is now necessary to transform the 
coordinate system lengthwise, the 
way envelopes feed into PostScript 
printers. The default origin (0,0) is at 
the lower left corner of the page, hut 
the coordinate system may be rotated 
and translated to suit. Think of a piece 
of paper on your desk upon which 
you place your right hand, palm up, 
with your index finger along the left, 
long side (the Y axis) and your thumb 
along the lower, short side (the X 
axis). Your hand represents the de¬ 
fault coordinate system, called a right 
hand coordinate system. The 
PostScript operator rotate turns the 
entire coordinate system (your hand 
with the thumb and index finger at 
right angles) around the present ori¬ 
gin counterclockwise the number of 
degrees specified by the number 
placed on the stack just beneath the 
rotate operator. 

The positive quadrant of X and Y 
values rotates off the page during a 90 
rotate operation. Therefore, we need 
to complete a coordinate translation 


before our paper is lined up correctly 
for landscape printing. PostScript 
shifts the coordinate system using the 
translate operator, which uses the val¬ 
ues of X and Y on the stack under¬ 
neath the operator. The sequence of 
PostScript objects: 0 -612 translate 
moves no distance along the X axis 
and minus 612 points (8.5 inches) 
along the Y axis. (Note that the shift is 
negative along the newly rotated Y 
axis.) The PostScript measurements 
are still along the index finger for the 
Y coordinates and along the thumb 
for X coordinates. The positive direc¬ 
tion is toward the fingertips. The 
landscape transformation (90 rotate 
followed by 0 -610 translate) effec¬ 
tively prints everything at 90 degrees 
to the original orientation of the 
paper. 

PE.CUD builds the PostScript 
strings and then writes them to the 
parallel port using the REXX function 
LIKEOUTO. The parallel port can be 
treated as a stream. Because 
PostScript is an interpreted language, 
these PostScript code strings are exe¬ 
cuted as soon as an operator string ar¬ 
rives at the printer. Nonoperator, or 
data, strings are pushed onto the 
stack as they arrive. 

TEXT POSITIONS ON ENVELOPES 

Determine coordinates for the text po¬ 


sitions on an envelope by measuring a 
regular sheet of paper with a standard 
No. 10 business envelope oriented 
lengthwise and centered or positioned 
to one side depending on your 
printer. The printer always thinks it is 
printing on a standard-size page, so 
we must make sure to print only in 
the area covered by the envelope. 
Figure margins are based on the stan¬ 
dard 8- 1 / 2 x 11 area. It is always a 
good idea to print on a full sheet of 
paper until the printing area lines up 
correctly. 

The final section of the print 
function hard codes the return ad¬ 
dress in the upper left comer of the 
envelope. Note how to move down 
one line by subtracting 12 points from 
the Y coordinate. The final command 
is the PostScript shoupage. PostScript 
and REXX seem to have been made 
for each other! 
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By MARKUS PELT-LAYMAN 


PDS Transfers Using 
EHLLAPI in REXX 


he Emulator High-Level Language 
M Application Programming Inter- 

m face (EHLLAPI) running under 

OS/2 Communications Manager provides 
users the capability to write client/server 
applications using emulated IBM 3270 ter¬ 
minals connected to IBM mainframes. 
Although EHLLAPI supports the Basic, C, 
COBOL, and Assembler languages, the 
power and flexibility of REXX significantly 
reduce programming effort and speed up 
development. 

EHLLAPI is available from almost 
every vendor that supports 3270 terminal 
emulation over 3270 emulator adapter 
cards, SDLC adapter cards, or LAN adapter 
cards under both OS/2 and DOS/ 
Windows. (The RLIM.ZIP shareware pack¬ 
age, available on the Rexx-R-Us BBS at 
(303) 4401351 and on other BBSs provides 
EHLLAPI support specifically for 
Enterprise REXX and Quercus REXX under 
DOS and Windows. However, the calling 
syntax is slightly different than that for 
OS/2.) 

THE 3270 WORLD 

The IBM 3270 family of terminals was al¬ 
ready widely used before the advent of the 
personal computer, A typical local configu¬ 
ration (shown in Figure 1) consists of an 
IBM 3274 control unity (CU) connected via 
a channel to an IBM 370/390 mainframe. 
The control unit can connect up to 32 IBM 
3270-type terminals via coaxial cable in a 
star configuration. Distances between CU 
and mainframe as well as between CU and 
terminal are limited without additional 
equipment. 

For remote connections, a different 
control unit is used, but the same 3270-type 
terminals can be attached to it, again using 
coaxial cable in a star configuration. The 


control unit in this case is connected using 
modems and phone lines to a Front End 
Processor (FEP), which is attached via a 
channel to the mainframe. 

Terminals come in two basic flavors: 
the older, dumb Control Unit Terminals 
(CUT), which rely heavily on process¬ 
ing logic in the CU, and the newer, smart 
Distributed Function Terminals (DFT), 
which off-load a lot of the terminal process¬ 
ing from the CU, 3270-compatible termi¬ 
nals come in many configurations and with 
many options, such as APL and Katakana 
keyboards, security card readers, as well as 
light pens, graphics, and IBM 328X printer 
support. 

While the 3270 terminal and control 
unit market was lucrative for both IBM and 
many compatible vendors, the introduction 
of the IBM PC saw the rise of 3270 emula¬ 
tion adapter cards. The initial problem for 
many large companies was that every desk 
that once had a 3270 terminal on it now 
had a separate 3270 terminal and a per¬ 
sonal computer (which didn't even talk to 
the mainframe). The solution was a 3270 
emulation adapter card, which allowed a 
PC to act as a real 3270 terminal by attach¬ 
ing via coax cable to a CU, eliminating the 
need for a standalone terminal. 

While the adapter card provided the 
low-level hardware compatibility to talk to 
the control unit, the PC required software 
to actually display output from the main¬ 
frame on the PC screen as well as accept 
keystrokes and send them to the main¬ 
frame, This emulation software was usually 
bundled with the adapter card and often 
specific to the adapter card. Each vendor 
had his or her own way of doing things. 

327QS IN A IAN WORLD 

The introduction of LANs (Local Area 
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Networks) created yet another problem. 
PCs that were already connected to the 
mainframe using 3270 emulation adapter 
cards needed a LAN adapter card to con¬ 
nect to the LAN. In large corporations, this 
meant having each PC wired using two 
coaxial cables: one for the LAN and one for 
the mainframe. The solution to this double 
wiring problem was to connect to the main¬ 
frame over the LAN somehow, thus elimi¬ 
nating the 3270 emulation adapter card and 
coax cable. Of course, this introduced even 
more ways to provide 3270 emulation, 
again with each vendor doing things in 
nonstandard ways. 

EHLLAPI was the answer to standard¬ 
izing the way in which PC applications 
could programmatically address 3270 emu¬ 
lation terminals, regardless of the physical 
connection from PC to mainframe. Under 
OS/2 Communications Manager, this is es¬ 
pecially obvious when one considers that 
OS/2 supports 3270 sessions using 3270 
emulation adapter cards, Ethernet adapter 
cards, Token-Ring adapter cards, SDLC 
adapter cards, and even async serial 
adapter cards, as well as many others. 


Regardless of the hardware and software 
configuration, EHLLAPI provides the same 
interface to all. 

LU 6.2/APPC VS. 3270 EMULATION 

Some people say 3270 emulation is old 
technology and that it will go the way of 
the dinosaur. IBM is pushing a new proto¬ 
col called LU 6.2 (also known as APPC or 
Advanced Program-to-Program Communi¬ 
cations) as the protocol of choice (the 3270 
terminal protocol is referred to as LU2). 

While it is true that LU 6.2 is better de¬ 
signed and allows far more flexibility than 
what is provided with 3270 terminal emu¬ 
lation, it does require that mainframe ap¬ 
plications be rewritten to specifically use it. 
From a mainframe application point of 
view, it is still far easier to write an applica¬ 
tion for a 3270 terminal than it is to write 
one for APPC. In addition, many legacy 
systems would require major program 
logic changes to accommodate APPC. 

This is partially due to the fact that ex¬ 
isting 3270 terminal applications are encap¬ 
sulated by a terminal monitor program 
such as CICS or TSO, which is responsible 



Figure 1 . Sample 3270 configurations. 
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for much of the VTAM network pro¬ 
tocol establishment and security au¬ 
thentication processing. Until all 
mainframe applications are converted 
to use APPC, many legacy systems 
using 3270 terminals will remain. 
3270 terminal emulation may elimi¬ 
nate 3270 standalone terminals but 
not 3270 mainframe applications. 
What EHLLAP1 can provide right 
now is a way of interfacing with such 
legacy systems and possibly even 
putting a new coat of GUI paint on an 
old 3270 character-based mainframe 
application. 


THE 3270 TERMINAL 

The original 3270 terminal consisted 
of a green monochrome monitor and 
a keyboard. The keyboard had a stan¬ 
dard QWERTY layout with 12 addi¬ 
tional program function keys (PF 
keys) for special functions on the 
right-hand side where the numeric 
keypad usually appears on personal 
computer keyboards. 

The monitor displayed a charac¬ 
ter-based (as opposed to graphics) 
screen 24 lines by 80 columns, with 
an additional status line at the bot¬ 
tom of the screen (called the Operator 
Information Area, or OIA) reserved 
for terminal session indicators (such 
as shift state, keyboard locked state, 
and so forth). While the original 3270 
models supported only limited dis¬ 
play attributes for each character, 
such as low or high intensity or invis¬ 
ibility, the later models support dif¬ 
ferent color and extended attributes 
such as reverse video and user-de¬ 
fined character sets (called 
Programmed Symbols in 3270 par¬ 
lance) as well as different screen 
sizes. 


FIELDS AND ATTRIBUTES 

What is displayed on the screen is de¬ 
termined by what is placed in the ter¬ 
minal's presentation space (PS) 
buffer. In its simplest form, the PS 
buffer acts like a PC video display 
buffer. For example, a 24-line-by-80- 
column screen has an associated 
1,920-byte (=24 x 80) PS buffer. To 
display the character "A" on line 1 
column 1 of the screen, place the byte 


red 

high-intensity input field 

green 

low-intensity input field 

blue 

low-intensity output field 

white 

high-intensity output field 


Table 1 . Basic color support. 


"A" in the first buffer location. The 
buffer address for the character at 
line 2 column 1 is 80 (or offset 79). 

Aside from straight text bytes, 
you can also place attribute bytes in 
the buffer. A buffer location set with 
an attribute byte marks the start of a 
new field. The value of the attribute 
byte describes some of the basic at¬ 
tributes for all characters that follow 
in the field up to the next attribute 
byte (the next field). Attribute bytes 
themselves display on screen as a 
blank (which cannot be modified via 
the keyboard). 

For example, a bit in the defini¬ 
tion of an attribute byte indicates 
whether the field should be displayed 
in high or low intensity. Another set 
of bits describes whether the field is 
an input field or output only field 
(not modifiable by the keyboard 
user). One more bit is reserved to in¬ 
dicate if the field has been modified 
(MDT or Modified Data Tag bit). This 
last bit is especially useful when read¬ 
ing the PS buffer, as it indicates a field 
that has been changed in some way 
(this bit can also be set by programs 
to simulate user modifications). 

The PS buffer wraps at the end of 
the screen: a field started by the last 
attribute byte will continue from line 
24 column 80 to line 1 column 1 un¬ 
less an attribute byte is put in line 1 
column 1 or line 24 column 80. 

EXTENDED ATTRIBUTES 

To support more than the basic attrib¬ 
utes previously described (intensity, 
input/output, and modified), three 
additional buffers are used that are 
conceptually similar to the PS buffer 
in addressing. These extended at¬ 
tribute buffers are used for: 

1. Extended highlighting (reverse 
video, blinking, and underlined) 

2. Extended colors (blue, red, pink, 
green, turquoise, yellow, and 
white) 

3. Programmed Symbols (usually 
used for graphics). 

Basic color support does not use 
extended attributes. A simple transla¬ 
tion scheme using the basic field at¬ 
tributes is used as shown in Table 1 

ATTENTION KEYS 

Following is the usual cycle for inter¬ 
action on a 3270 terminal: 

1. A mainframe program displays 
output on screen and waits for user 
input 

2. The user types information in 
input fields displayed on screen 
and presses an attention key. 


The user signals that he or she is 
done typing input into fields by 
pressing one of the attention keys. All 
keys other than attention keys are 
handled locally, and no data is trans¬ 
ferred to the mainframe until an at¬ 
tention key is pressed. The following 
are the attention keys: 

• Enter key 

• Clear key (also clears screen) 

• PA1, PA2, and PA3 keys 

• PF1 through PF24 program func¬ 
tion keys 

• Test Req key. 

In addition, certain terminal at¬ 
tachments, such as a card reader, 
magnetic slot reader, hand scanner, 
or light pen, can also signal attention. 

MAINFRAME PROGRAMMING 

Under MVS TSO you can use the 
TPUT (Terminal PUT) and TGET su¬ 
pervisor call instructions/macros to 
send and receive 3270 data streams 
respectively. At a higher level, the 
panels used by ISPF and the screen 
definitions used by CICS are trans¬ 
lated to 3270 data streams. 

3270DATA STREAMS 

From the point of view of the main¬ 
frame, the 3270 terminal is driven by 
sending it commands. The basic com¬ 
mands are: 

• Write 

• Read buffer 

• Read Modified. 

When a mainframe application 
sends the 3270 terminal a Write com¬ 
mand, it is followed by a sequence of 
data characters mixed with orders. 
There is a concept of current buffer 
address (or just buffer address for 
short), which is incremented when¬ 
ever a data character is encountered 
in the write data stream (after the 
character is put into the PS buffer at 
the current buffer address). The or¬ 
ders encountered in a write stream 
can manipulate the PS buffer as well 
as alter the current buffer address. 
The changes made by the write 
stream to the PS buffer in turn change 
what is displayed on the screen of the 
terminal. 

ORDERS 

Table 2 shows the various orders that 
can be included in a 3270 data stream 
and the effect each has on the PS 
buffer and current buffer address. 

When a Read Buffer command is 
sent by the mainframe to the 3270 ter¬ 
minal, the terminal transmits back to 
the host the entire PS buffer. The for¬ 
mat of the returned data is data char- 
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acters mixed with SF orders for each 
field attribute byte (so the mainframe 
application can decipher where each 
field started). 

The Read Modified command 
works similarly but returns data and 
SF orders for only modified fields 
(fields with the MDT bit on in their 
basic attribute byte.) Either the MDT 
bit was turned on by the user making 
modifications to the field using the 
keyboard, or the mainframe applica¬ 
tion sent the attribute byte originally 
with the MDT bit already on. The 
MDT bits are reset once all modified 
fields have been transmitted. The 
Read Modified command also adds 
SB A orders before every SF order to 
indicate where each modified field 
started. 

The data stream returned by 
Read and Read Modified commands 
is preceded by three bytes, including 
the AID (Attention Identification) 
character, which identifies the key 
the user pressed to cause the Read or 
Read Modified to be completed. 

PC PROGRAMMING—EHLLAPl 

While 3270 data streams are used to 
access the 3270 terminal PS buffer 
from the mainframe, EHLLAPI is 
used to access the emulated termi¬ 
nal's PS buffer as well as send key¬ 
strokes from the PC side. The basic 
idea behind EHLLAPI is to send key¬ 


strokes and read the screen (that is, 
access the PS buffer) to emulate what 
a human user would do manually. 

The EHLLAPI specification pro¬ 
vides some 50-plus functions. 
Luckily, only a handful are needed 
for most applications. Before dis¬ 
cussing the most often used 
EHLLAPI functions in detail, let's di¬ 
gress to the problem that triggered 
the writing of this article. 

PC/MAfNFRAME FILE TRANSFER 

Both MVS TSO and CMS include a 
command called IND$FILE, which can 
be used to send or receive single files 
from a 3270 emulator to the main¬ 
frame. The emphasis here is on the 
words single file (although the 
newest VM/CMS version of IND$FILE 
does allow multiple files using wild¬ 
card characters). Most terminal emu¬ 
lator products (including OS/2) pro¬ 
vide a SEND and RECEIVE command on 
the PC side to initiate a file transfer to 
or from the mainframe, respectively: 

IND$FILE GET host file options 

or 

INDjFILE PUT hostfile options 

The SEND and RECEIVE commands 
themselves issue an INDSFILE com¬ 
mand to the mainframe host under 


SBA Set Buffer Address order changes the current buffer address to that 
specified in the order 

RA Repeat to Address order fCls the PS buffer with the character speci¬ 
fied in the order from the current buffer address to the one specified 
in the order. 

SF Start Field order inserts a basic attribute byte specified in the order 
into the PS buffer at the current buffer address. This starts a new 
Held* 

$FE Start Field Extended order is similar to SF order except the order may 
include both a basic attribute byte as well as extended attribute bytes. 

MF Modify Field order modifies basic and/or extended attributes for the 
field that starts at the current buffer address 

SA Set Attribute order changes the extended attributes for a character at 
the current buffer address 

PT Program Tab order changes the current buffer address to the next 
input field (starting from the current buffer address) 

EAU Erase All Unprotected order sets all input fields to nulls from the cur¬ 
rent buffer address to that specified in the order. 


Table 2 ; 3270 Data Stream orders . 



Simple 

Database 

Management 


dbfREXX 
Version 2 

Now you can have 
simple database 
management from 
your REXX programs, 
without spending a 
lot of money! 

dbfREXX extends 
REXX with functions 
to read, write, and 
create database files 
and indexes. 

Files supported are: 
DBF, DBT, FPT, 
NTX, & NDX. 


$99 

Visa and MasterCard 


dSOFT Development Inc. 

713 - 537-0318 

Voice & Fax j 


SUMMER 1995 


25 



















the covers, so the user is never really 
aware of the command syntax of the 
INOSFILE host command. If you want 
to check if you have IND$FILE on your 
host, simply try the IN0$FILE command 
without any operands from a 3270 
session window. An indication that 
the command was not found proba¬ 
bly means IND$FILE is not available. 

The syntax of the SEND and RECEIVE 
OS/2 commands is fully explained in 
the OS/2 online help (issue HELP SEND 
or HELP RECEIVE from an OS/2 com¬ 
mand session). In brief, the syntax is: 


SEND pcfile [session:] hostfile 
[options] 


and 

RECEIVE pcfile [session:] hostfile 
[options] 


where all lowercase items should be 
replaced with actual values and 
brackets indicate optional items (do 
not enter the brackets themselves). 
Check the OS/2 online help for the 
syntax details. 

During the actual file transfer, 
the session window usually goes 
blank. This is to prevent the user 
from becoming confused if he or she 
sees the file transfer data displayed 
(which may include non viewable char¬ 
acters if binary data is transmitted}. 

PC VS. MAINFRAME FILES 

PC files come in two basic flavors: 
ASCII text files and proprietary bi¬ 
nary data files. Mainframe files are 
distinguished by file organization, 
record format, record length, and 
block size. During file transfer, differ¬ 
ences in file structure and contents 
may have to be resolved. Following 
are the major problems: 

* ASCII versus EBCDIC encoding of 
text data. The PC uses ASCII en¬ 
coding for text characters, and the 
mainframe uses EBCDIC encoding. 
This means that whereas the letter 
"A" is represented in ASCII as a 
byte whose value is 65, it is repre¬ 
sented in EBCDIC as a byte with 
the value 193. Obviously, without 
translation, an ASCII file will be 
printed or displayed as garbage on 
a mainframe. Similarly, a main¬ 
frame file containing names and 
addresses will look like garbage 
when typed or printed on a PC 
without translation. 

The SEND and RECEIVE commands 
(and HDlFJLE) can translate ASCII 
to EBCDIC and vice versa when 


the option "ASCII" is added to the 
end of the command, 

* CR/LF translation to records and 
vice versa. For text files on the PC, 
a line or record is marked by the 
presence of a carriage return 
and/or line feed character. On the 
mainframe, text files do not in¬ 
clude these control characters. 
Instead, records in a file are all the 
same length (RECFM=F) or vari¬ 
able with a 4-byte record descrip¬ 
tor word preceding each record in¬ 
dicating the length of the record 
that follows. Clearly, when receiv¬ 
ing a mainframe file without 
CR/LF control characters, the file 
is not readable on the personal 
computer. Conversely, the pres¬ 
ence of CR/LF data will display as 
garbage on the mainframe and 
possibly cause problems with lines 
being split or running together 
erroneously. 

Fortunately, the "CRLF" option 
on the SEND and RECEIVE commands 
will translate records for text files 
correctly in this case. 

* Record and block descriptor words 
for variable-length mainframe files 
are always stripped when sent to 
the PC by XNDIFILE. This in effect 
means that variable-length files are 
unusable unless they are text files 
and you use the "CRLF" option. 

* Little-Endian vs. Big-Endian prob¬ 
lems can occur for binary files that 
include numeric values. The main¬ 
frame stores numeric values larger 
than a byte in most-significant- 
byte-first sequence. For example, 
the value 256 is stored in a file on 
the mainframe as two bytes '01'It 
and '00'X. On the PC, the least-sig¬ 
nificant bytes are always stored 
first (for example, 'OQ'Jt '01'X 
means the value 256). 

Unfortunately, there is no way 
to know which values would re- 
quire switching bytes around with¬ 
out knowledge of a binary file's 
record layout and structure. 
IND$FILE will not provide any assis¬ 
tance for this problem. You may 
need to massage the file after trans¬ 
fer to make it usable on the target 
system in this case. 

* File naming problems may occur. 
Since PC file names have an 11- 
character (8.3) format and main¬ 
frame PDS member names have 
only eight characters, something 
will have to give. On the PC side, 
the three-letter filename extension 
usually indicates file type, which 
on the mainframe is normally indi¬ 


cated by the last qualifier of the 
data set name. For example: 

C:\HYPRGJ\mfFILE.ASM 

could be translated to: 

'MYUSRID.HYPROJJSH(HYFILE)' 

However, even with such a 
translation scheme, naming conven¬ 
tions for member names are stricter 
than those for PC file names (which 
may include numerics as the first 
character, as well as special symbols 
not allowed for member names). 

PARTITIONED DATA SETS 

MVS supports a multitude of file or¬ 
ganizations, one of which Is called 
the Partitioned Data Set (PDS). A PDS 
is a collection of homogeneous se¬ 
quential files. All the member files (or 
members) must share the same logi¬ 
cal record length (LRECL), block size if 
blocked (BLKSIZE), and record format 
(RECFR=F for fixed-length records or 
RECFM=V for variable-length records). 
With the exception of the homogene¬ 
ity requirement, PDSs are similar to 
PC directories. While the mainframe 
has utilities to copy and manipulate 
entire PDSs and the PC has utilities to 
do the same for directories, the 
IND$FILE file transfer program has no 
direct support for PDS files. 

To transfer an entire PDS, each 
member will need to be sent individ¬ 
ually (that is, a SEND or RECEIVE com¬ 
mand must be issued for each mem¬ 
ber separately). This is a minor 
inconvenience for transferring a small 
number of members, but it is a show- 
stopper if you have to transfer a PDS 
with a hundred or more members. 
The solution, of course, is to write a 
small REXX program to issue the 
commands for us. 

SPECIFICATIONS 

Ideally, we would like a command to 
upload a PC directory to a mainframe 
PDS and another command to down¬ 
load a mainframe PDS to a PC direc¬ 
tory. For the upload to a PDS to 
work, ail files in the source PC direc¬ 
tory must share the same file charac¬ 
teristics (remember the homogeneity 
requirement of PDSs). In addition, we 
should probably allow for the specifi¬ 
cation of the 3270 session to perform 
the transfer as well as the option to 
pass the CRLF and ASCII options for 
text files. So the full syntax becomes: 

UPPDS pedir pdsname [session:] [options] 
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DOWNPDS pdsname pcdir[session:] [options] 

Both the pcdir operand in the 
UPPDS command and the pdsname 
operand in the DOWNPDS command sup¬ 
port wild card characters (? for single 
character match and * for multiple 
character match) to specify that only 
those files or members that match the 
wild card specification be transferred. 
For example: 

DOWNPDS 'SYSl.HACLIB(IEF*r C:\MAC5 

will only download members whose 
names start with the prefix iEF. 

EHLLAPf APPUCA TIDN DESIGN 

As previously stated, the basic idea 
behind EHLLAPI is to send key- 
strokes and “read" the emulated ter¬ 
minal's screen, that is, to simulate 
what a user would do manually. A 
good starting point for design, there¬ 
fore, is to write down what exactly a 
user would do manually. 

To upload files from a PC direc¬ 
tory to a mainframe FDS: 

1. The user issues a DIR command 
from an OS/2 command window 
to get the names of all the files in 
the PC subdirectory to be up¬ 
loaded. 

2. The user writes down on a notepad 
a list of all the files to be uploaded. 

3. The user makes sure that he or she 
has a 3270 session with the target 
host. 

4. The user checks that the target PDS 
exists using the TSO LISTDS com¬ 
mand and, if not, creates it on the 
mainframe using the TSO ALLOC 
command. 

5. The user issues a SEND command 
from an OS/2 command window 
for each file in the list and checks 
to make sure each upload finishes 
successfully. 

To download members of a PDS 
to a PC directory: 

1. The user makes sure that he or she 
has a 3270 session with the target 
host 

2- The user issues a LISTDS TSO com¬ 
mand to get a list of all member 
names in the PDS. 

3. The user writes down a list of all 
the members to be downloaded. 

4. For each member in the list, the 
user issues a RECEIVE command 
from an OS/2 command window 
and checks to make sure each 
download finishes successfully. 

COMMAND REQUIREMENTS 

Aside from using the SEND and RECEIVE 


OS/2 commands to perform the 
transfer of individual members, we 
will also need some way to collect the 
names of files to be transferred. On 
the PC we will need to get all names 
of files in a given directory on disk, 
and on the mainframe we will need 
to get the names of all members of a 
partitioned data set. 

The obvious answer for the PC 
side would be to issue the OS/2 DIR 
command for the directory of interest 
and parsing the returned output. 
However, there is a simpler way 
using the SysFileTree function pro¬ 
vided with OS/2, which is explained 
later. 

On the mainframe, the TSO LISTDS 
command with the MEMBERS option will 
display a list of all members for a 
given PDS. Its syntax is: 


LISTDS dsnarae MEMBERS 
A typical response might be: 



MYUSRID.LIBJSM 
—REC FM-LRECL-8L KSIZE-D SO RG 
FB 80 80 PS 

—VOLUMES— 

D95LIB 
—MEMBERS— 

ABC 

DEF 

m 


DESIGN CONSIDER A TIONS 

Our preliminary design will call for 
the following subroutines: 

* A GetFileNames routine, which will 
build a list of file names found in a 
PC directory using the SysFileTreeO 
function 

* A GetMemberNames routine, which will 


fiILapi( 'Connect', session) 

Establishes a connection between your REXX program and the 3270 session 
specified by the single session letter. 

hllapit'Disconnect*,session) 

Breaks the connection previously established with the Connect verb. 

Kllapif' SetSessionParms', 'options') 

Changes some user-settable session parameters. This application uses the 
TWAIT option to cause Wait verbs to timeout after a long wait. 

hllapif'QuerySessionStatussession) 

Returns information about the session. This application needs to know the 
number of rows and columns used for the presentation space. 

laiapifSendkeys, 'string') 

Simulates entry of keystrokes on the 3270 session. Each character in the 
string is sent as a keystroke. Use special mnemonics for special keys: @C - 
Clear key, @E - Enter key. 

hllapi('iait') 

Waits until the 3270 session's keyboard is unlocked, that is, when it's O.K. to 
send keystrokes. 

KIIapi{'Pause', half secsf, session]) 

Waits specified number of half-seconds. 

hUapi('Seardi_P$%'string') 

Searches the PS buffer for a specified string and returns the buffer position 
of the found string, 

hllapi('Copj_PS^to_str' »pos .length) 

Returns a string that contains a copy of the entire PS buffer. 

hHapiC'SendFile','pcfile session: pdsnafte options') 

Issues a SEND command to transfer a hie from the PC to the mainframe. 

hHapi('fieceiveFil*%'pdsnaiiie session: pcfile options') 

Issues a RECEIVE command to transfer a file from the mainframe to the PC. 


Table 1 Commonly used EHLLAPf verbs and operands 
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Figure 2. GetMemberNames routine. 


build a list of PDS member names 
by issuing a LISTDS TSO command. 

• A routine that will issue a SEND 
command for each filename in a 
list or a RECEIVE command for each 
member name in a list. 

• A routine to create a new PDS if 
UPPDS detects that the target PDS 
name does not exist. 

• INIT routine to initialize the appli¬ 
cation. This breaks the big job into 
five smaller jobs. 

CALLING EHLLAPI 

Only one function in SAAHLAPI.DLL 
provides all EHLLAPI support under 
OS/2. Its calling syntax is: 

result = HLLAPI('verb' [, operands]) 

where 'verb' is a text string that iden¬ 
tifies one of over 50 actions and 
operands are specific to the verb 
specified. Fortunately, we need only 
10 of the most often used verbs for 
our application, which is shown in 
Table 3. 

Before you can call an external 
function under OS/2 REXX, you 
must first register it by calling the 
RxFuncAddQ function. This needs to be 
done only once per OS/2 boot-up. 
Once registered, a function is known 
to all REXX programs: 

RxFuncAdd('hllapi','saahlapi','HLAPISRV') 

The result of this function is ei¬ 
ther 1 if successful or 0 if not. The 
first argument is the name you will 
use in your programs for this func¬ 
tion. The second is the name of the 
OS/2 DLL in which the function re¬ 
sides. The third argument identifies 
the name under which the function is 
known in the DLL. Usually the first 
and third arguments specify the same 
name to avoid confusion. However, if 
you have a favorite name for a func¬ 
tion or the same name is used in mul¬ 
tiple DLLs, renaming the function at 
registration time works great. 

INITIALIZATION 

The initialization routine registers the 
EHLLAPI external function and pre¬ 
pares the user-specified session (or 
session A by default) as follows: 

1. Connect REXX program to session 
(Connect verb). 

2. Wait for session keyboard to un¬ 
lock (Wait verb). 

3. Send the Clear key to clear the 
screen (SendKeys verb). This is done 
so we do not interpret old data on 
the screen. 
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4- Wait again for the keyboard to un¬ 
lock. 

5. Get the screen size (rows and 
columns) for later use (Query $€S- 
sionStatus verb). 

The session is now ready for use. 

GETTING PC FILE NAMES 

To upload all files from a PC direc¬ 
tory, we need to build a list of file¬ 
names. OS/2 REXX provides a 
SysFileTreeO function that will place 
all filenames in a user-specified stem 
variable: 

Sj sFileTree("C:\ASH\*.*","members >",F) 

After the above call, the com¬ 
pound symbol members*Q will contain 
the number of filenames found and 
the compound symbols members. 1, mem¬ 
bers. 2, up to members.n (where n = mem¬ 
ber s.O) will contain the fully qualified 
file names, including the full path 
name of the directory. 

GETTING PDS MEMBER NAMES 

The most complex part of this appli¬ 
cation is the building of the list of 
PDS member names when download¬ 
ing a PDS. This is where we make the 
most heavy usage of EHLLAPI and 
need to take care of some ugly details 
such as scrolling the output of the 


LISTDS TSO command if it is longer 
than one screen's worth. 

In TSO READY mode, when a 
screen's worth of data has been dis¬ 
played, three asterisks are placed at 
the end of the output to indicate that 
more output is to follow. The user 
can hit the Enter key to get the next 
screen's worth of data. 

Figure 2 shows the logic to do 
the scrolling and scanning* It consists 
of a double do loop construct. The 
inner loop processes each detail line 
on each screen of data (adding mem¬ 
ber names it scans to the list being 
built)* While scanning, member 
names are checked against any wild 
card member name specification the 
user may have entered on the DOWN PDS 
command. 

The outer loop keeps checking if 
the last line ended with three aster¬ 
isks and, if so, sends the Enter key 
press. If no asterisks are found, the 
output from LISTDS is presumed to be 
complete. 

TRANSFERRING THE FILES 

The final step, transferring the files, 
consists of a small do loop with an 
EHLLAPI call for the SendFile or 
ReceiveFile verb (see Table 3 for syn¬ 
tax). Note that these verbs call the 
SEND and RECEIVE commands, which 
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available in machine-readable form at the following locations: 

The REXX-R-Us BBS at (303) 440-1351 in file PDSXFER.ZIP 
in the Info-REXX multimedia help file available from 
Pelt Industries. 

The OS2DF2 CompuServe forum in file PDSXFER.ZIP 

VTAM Programming (IBM order number SC23-QI15) 

IBM 3270 Information Display System: 3274 Control Unit Description 
and Programmer's Guide (IBM order number GA23-G061) 

EHLLAPI Programming Reference (IBM order number SO4G-1027) 

OS/2 REXX online help 

OS/2 Communications Manager/2 online help 


will not have access to the 3270 ses¬ 
sion unless our program disconnects 
from the session first. Also, the return 
code from each file transfer should be 
checked. If not O.K., all further trans¬ 
fers are skipped (to avoid repeating 
the same error). 



CREATING A NEW PDS 

One final snag needs to be overcome: 
the SEND command will fail if the tar¬ 
get PDS does not exist on the main¬ 
frame (actually, RECEIVE also fails if the 
target directory does not exist)* To 
automate creation of a new PDS, the 
UPPDS command includes logic to 
prompt the user for allocation infor¬ 
mation needed to issue the ALLOCATE 
TSO command to create a new PDS. 


PUTTING IT All TOGETHER 

The DOWNPDS and UPPDS programs are 
around 320 lines each, including com¬ 
ments* While not perfect (for exam¬ 
ple, asynchronous messages from the 
operator to the TSO terminal can 
wreak havoc with displayed output 
on the screen), they exemplify many 
of the techniques needed to success¬ 
fully use EHLLAPI. 

While LU 6,2, APPC and APPN 
peer-to-peer communications allow 
tighter integration between PC and 
mainframe, EHLLAPI and REXX pro¬ 
vide a powerful combination to add 
some new life to old applications 
using 3270 terminal emulation. 
REXX's strength in string manipula¬ 
tion for parsing returned output as 
well as building command lines make 
for quick, flexible, and powerful 
programming. 


Markus Pelt-Layman has been a software 
developer for over 22 years. He is author of 
several commercial software packages on 
IBM mainframes and PCs f including 
"AF/Operator" (now sold by Candle Corpi and 
is coauthor of the REXX interpreter in the 
OPS/MVS product (now sold by Legem Corp). 
His areas of interest include computer opera¬ 
tions automation, computer language pro¬ 
cessing t and computer/human interface opti¬ 
mization. He has a B.S. degree in 
mathematics, and a M.S. degree in operations 
research from Stanford University. He is cur¬ 
rently working on RexxAnne, a REXX compiler 
for OS/2, Windows NT, and Windows. He can 
be reached at Pelt Industries (800) 741-4322 ; 
by e-mail at MarkPQPeltlnd.com, or by fax at 
(303) 442-3198. 


SUMMER 1 9 S 5 


29 









H^lncludes product demos and 
white papers 


Hie Software 
Development/ 
Computer Language 

Featuring: 

Product Information Links with 
The Programmer’s Paradise 0 Catalog 


Before you buy, get product informa¬ 
tion—fast —from the most trusted 
sources in the industry* 

And become a more productive program¬ 
mer too! Imagine 5 years of back issues of 
Software Development znd Computer 
Language magazines—available on one new 
CD for the first time ever. Includes feature 


programming, languages, 
object-orientation, client/ 
server, database program¬ 
ming, and much more. 

Reliable, thorough 
programming products—fast and easy . 

The Programmers Paradise Catalogs best 
selling products are featured via hundreds 


articles, regular columns, source code, 
cables, and comprehensive, comparative 
product reviews from the June 1989 
through the December 1994 issues. 

The Software Development CD is the 
most authoritative source of practical 
technical information in the business , 

Software Development explores the products, 
practices, and technologies that address 
issues concerning todays corporate develop¬ 
er. Learn from programming greats like 
Grady Booch, Stan Kelly-Bootle, Ed 


of product highlights, informative white 
papers, and revealing demos electronically 
linked to the over 1000 Computer 
Language/Software Development product 
reviews and mentions. The industry's lead¬ 
ing products and software publishers are 
represented, including Microsoft, IBM, 
Borland, Sheridan, Pro to View 
Development, Mortice Kern Systems, 
Lifeboat Publishing, Blue Sky Software, 
Apex Software, Crescent Software, LEAD 
Technologies, and Srarbase Corporation. 


ffl^Over 20,000 hypertext 

links—you can easily refer¬ 
ence articles, figures, list¬ 
ings and more 

III^Full source code listings for 
magazine articles—use them 
in your own projects 

ilH^Full text searching—search 
for any word or phrase any¬ 
where in any article 

ilI+Conv€ rnient bookmarks let 
you save your place 

ill^Runs under Windows—use it 
alongside your 
compiler/development envi¬ 
ronment 


Yourdon, Warren Keuffel, Roland Racko, 
and Bruce Schneier about design, team 


The easy-to-use hypertext interface lets you 
find the information you need—quickly! 


11^ Look up articles by year, 
month, and title—or do a 
search 


Software Development/Computer Language CD 


I The Snjhtwre Drtvfopmeritt Computer Language CD is available approximately April 17, 1995. 

My price is $49.95 plus $3.00 shipping US/Canada {,$12.50 all other countries). California residents, add $4.12 sales tax. 
New York and New Jersey residents, add applicable sales tax. Clip out or photocopy this form. 



>My 

$ 49.95 


Name ipi*** [Mint dodfi 
Address 


Phone Number n 


I 

| City/Staw/Zip Country 

| Here's how Tin paying (circle one); VISA MC AMEX Check enclosed 


I 


Credit card number lindu* 


Expiration date 


Signature required 


OS/2 □ 


TO ORDER CALL: 

1 - 000 - 892-1186 

FAX ORDERS: 

1 - 908 - 389-1390 

Use this fomi 

MAIL ORDERS: 

Software Dcvelopmenl/Compuler Language CD/Attn: 
Philip Kcppeler GOO Harrison St. San Francisco, CA94107 

INTERNATIONAL: 

Mail/fax in this order form 













If you Ve never seen Object REXX in action, here's your chance, This product is a major 
improvement in the language, compatible with 0S/2's SOM and Workplace Shell. 

By BRET CURRAN 



Object REXX- 
HowCool? 


he best way to start any computer- 
related article, especially if your 
audience consists of the guru appli¬ 
cation developers of the industry, is to jump 
right in with a sample program. Figure 1 
does exactly that by showing you what an 
Object REXX program looks like. 

Even though space does not allow a 
more descriptive analysis of what the 
WayCQOL program is doing (other than 
what the comments provide), 1 wanted to 
start by giving you a flavor of Object REXX. 
It should look familiar to you if you've ever 
seen REXX code or have done any object- 
oriented programming. 

This article will cover the following: 

* What is Object REXX? 

* Using Object REXX to Work with the 
Workplace Shell (WPS) 

• Other COOL things to do with Object 
REXX and WPS, 

WHAT IS OBJECT REXX? 

Object REXX is the follow-up version of 
REXX in the OS/2 world. Object REXX is 
currently in beta and is available via the 
IBM Developers Connection program (be¬ 
ginning with DevCon 6). There also hap¬ 
pens to be an Object REXX for Windows, 
which is also in beta. 

Object REXX supports both procedural 
and object-oriented programming, in the 
same program if you'd like, and will be 
completely upward compatible with the ex¬ 
isting REXX on OS/2. This compatibility 
means that existing REXX programs, REXX 
function packages, and REXX products and 
environments will all work unchanged on 
Object REXX, 

Who Will Be Interested in Object REXX? 

Probably everyone will be interested in 
Object REXX, especially when it becomes an 
integral part of the operating system. 
Following are some people who will defi¬ 
nitely be interested: 

• Newcomers to object-oriented program¬ 


ming will find that Object REXX is an 
easy way to get their feet wet. Object-ori¬ 
ented concepts can be exercised quickly 
and easily with Object REXX, especially 
compared to other tools available today. 
Object-oriented programmers will enjoy 
Object REXX because of its ease of use 
and implementation. It could easily be¬ 
come the object-oriented prototyping tool 
of choice. 

Experienced object-oriented program¬ 
mers will find that Object REXX is a pow¬ 
erful, state-of-the-art object-oriented pro¬ 
gramming language, featuring multiple 
inheritance, object-based concurrency, 
and both class- and instance-based pro¬ 
gramming. 

WPS developers, those interested in 
working with the WPS, or those learning 
how to program the WPS interface will 
enjoy the capability that Object REXX 
provides to easily and quickly experi¬ 
ment with the shell's API, 


/**t*t*t****tt****t*44ti**$**t*t* ¥! t*f¥*t**t***t*************/ 

A Program name: 00RE3U.CHD */ 

Instance=.OQREXIT new A Create a new instance of the */ 
A OOREXX class defined below */ 
instance'HowCool A Invoke the HowCOOL Method */ 

A End of executable code; start of class/method definition*/ 

::CLIS5 OOREXX A Define the OOREXX Class */ 

::METHOD HowCQGL A Define the HowCool Method */ 

say ('OOREXX is MIT Cool!']]'01'x)"copies(5) 

A Use the copies method (from the */ 
A STRING class) to create output */ 
/M*****tw*t ************ ************************** *********/ 

Output from WayCQ0L.CMD 

/*********************************************#*************/ 
OOREXX is MIT Cool! 

OOREXX is WIT Cool! 

OOREXX is WIT Cool! 

OOREXX is WIT Cool! 

OOREXX is WAT Cool! 

/tut*********************+*#*****************+***************/ 

Figure 1 1 OOREXX: an Object REXX sample program. 
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/* Program Name: SETOBJID.CMD ♦/ 
/* OS/2 Developer Magazine: July/August, 00 or REXX, p. ?? ♦/ 
/* Article Title: 0bjectREXX"WayC00L ♦/ 
/* Author: Bret Curran */ 
/* Infrastructure Incorporated */ 
/* Internet: (bretcCibm.net) ♦/ 
/♦ Phone: 800-496-3042 ♦/ 
/* Description: ♦/ 
/* This program will set an objectid for a specified object. */ 
/* You can specify the object with the WPS title and folder */ 
/♦ location. Once the ObjectID is set, then the object can */ 
/♦ be manipulated via the ObjectID from Classic Rexx ♦/ 
/♦ Program requirements */ 
/* Object Rexx must be loaded */ 
/♦ Object Rexx wpfind.cmd must be PATHed ♦/ 


use arg argStr 
args ■ arg$tr"strip 

parse var args path V title V objectid 


/♦ First, look in the 3rd parameter for an objectid */ 
/♦ If it's there, then parse accordingly, */ 
/* else */ 
/* if the objectid is in the second parameter then */ 
/♦ parse with only two parameters passed */ 
/♦ else there's an error in the parameters ♦/ 


if objectid'pos('<') \« 0 then 
do 

path * path'strip('B',' M ') 
title = title“strip('B','"') 
objectid a objectid'stripC'B','"') 
end 
else 
do 

if title“pos('<') \*0 then 
do 

objectid * title"strip('B','"') 
title * path'strip('B',' M ') 
path*" 
end 
else 
do 

say 'Syntax:' 

setobjid path title objectid 
where 

path is the title of folder(s) delimited by 
omit if the desktop is the only folder 
title is the title of the target object; 

use If for split titles 
objectid is the desired objectid 
(must specify "<" and ">■) 
all values are case sensitive 
separate the 3 parameters with commas 

examples 

setobjid "OS/2 System;Information", "Multimedia", "<MM>"' 
setobjid "Internet", "<IFolder>" 


end 


say ' 
say 
say ' 
say ' 
say ' 
say ' 
say ' 
say ' 
say ' 
say ' 
say 
say ' 
say ' 
say ' 
exit 1 
end 


/* if path is blank, then there's only two parms ♦/ 

/♦ otherwise, concatenate the path and title with a semicolon ♦/ 
/♦ and then have wpfind go get us the object ♦/ 

if path*" then 
obj*wpfind(title) 
else 

obj*wpfind(path';'title) 


Figure 2. SETOBJID program (continued on page 31). 


The Power of Object REXX. The 

power of REXX, especially on the 
OS/2 platform, has been increasing 
steadily in recent years. This is due 
mostly to the increased number of 
available development tools and li¬ 
braries. REXX itself also has been im¬ 
proved—by at least several orders of 
magnitude. The fact that it is an ob¬ 
ject-oriented language brings it into 
another class (pun intended) of pro¬ 
gramming languages. Couple that 
with REXX's upward compatibility, 
and you have all this great new stuff 
while not losing anything from be¬ 
fore. 

The power of REXX extends into 
many different facets of program¬ 
ming, especially on the OS/2 plat¬ 
form. My personal favorite is its abil¬ 
ity to work with OS/2's user 
interface, the Workplace Shell. 
("Using REXX to Customize the WPS, 
Parts 1 and 2," IBM Personal Systems 
Technical Solutions , April, July, 1993). 

Object REXX extends the power 
to work with the WPS much further 
than before, primarily because it can 
work with and manipulate System 
Object Model (SOM) objects. This 
means you can use and reuse SOM 
objects whether they were created in 
C, C++, or any other SOM-supported 
language. And because the WPS is 
based on SOM objects. Object REXX 
allows you to work directly with any 
of the WPS objects via the actual ob¬ 
ject methods. 

USING OBJECT REXX 
TO WORK WITH THE WPS 

Working with the WPS using 
"Classic" REXX turned out to be more 
an art form than anything. The basic 
functionality was provided through a 
few functions in REXXUTIL.DLL. 
While these functions allowed you to 
create many objects and even modify 
some, there were quite a few serious 
limitations to using Classic REXX to 
work with the WPS. 

The fundamental limitation was 
that each and every WPS function or 
method that was added or modified 
had to be replicated by someone in 
REXXland, which caused delays and 
limitations in the capabilities pro¬ 
vided with REXX. An additional dis¬ 
advantage was that only object set¬ 
tings that had setup strings vs. just 
object styles could be manipulated via 
REXX. This meant that if you could 
work with a WPS object, chances are 
good that you could perform only a 
limited number of actions. And last, 
but certainly not least, the most frus- 
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trating limitation had to be WPS ob¬ 
jects that did not have ObjectIDs, If an 
object did not have an ObjectID or 
was not a WPFileSystem object, there 
was just nothing you could do with 
the object from a REXX perspective. 

Object REXX to the Rescue , All of 
those limitations are history when 
you move to Object REXX. 
Essentially, you can work with any 
WPS object just as if you were pro¬ 
gramming from a C or C++ perspec¬ 
tive (only more easily). You can run 
any WPS method on the object, com¬ 
pared with a predetermined finite set 
of REXX functions. Plus, the ObjectID 
limitation is gone as well, although 
you can still use it if you'd like. With 
these limitations removed, you can 
see that the world of Object REXX and 
WPS is going to be quite an interest¬ 
ing one, and the easiest way to see 
that is with an example* 

The SETOBJID Example . SETOBJID 
(Figure 2) is an example of an Object 
REXX program that provides a solu¬ 
tion to a problem with Classic REXX. 
Remember, Classic REXX can work 
with an object only if it has an 
ObjectID. The SETOBJID program 
will allow you to specify an object by 
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Figure 2. SETOBJID program (continued from page 301. 
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includes myaity-free 
distribution rights. 


Develop professional quality multimedia applications with VX-REXX! 

* Circular Slider and Animated Graphic Push Button objects. 

* Create custom animation frame sequences! 

* Real-time control of OS/2 multimedia devices. 

* ampmrx, edaudio, cdxa. digital video, sequencer,, wav&audio, and videodisc, 

+ Nolily, NolReady, Pause, Play, Record, Seek, and Slop notification events. 

* Play digitalvideo movies in an Ultimotion window or any VX REXX window. 

You can even play movies and animations in a VX-REXX entry field object! 

Get started developing state-of-the-art multimedia applications! Order raw 
and receive the Multimedia Object Pack for only $99.95 {normally $150), 

DB Technologies, Inc. Sales Department: 8OO-63Q-07Q3 

2420 Briar Oak Circle Tech Support: 813-370-3760 

Sarasota, Florida 34232-6100 Fax: 813-377-7392 

CompuServe: 72123,3661 

Internet: 72123.3661 ©CompuServe.com 

VX-hEXX i* A lrodomarK oi Wataan International Corporation. 

OS/2 and Ulttmotton are trademarks of th* i8M Corporation. 
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REXX Diagnostic 
Commander 
Makes REXX 
Debugging Easy 


Software developers, ad¬ 
ministrators, and all OS/2 pro¬ 
fessionals can efficiently code 
and test REXX command files 
in a completely interactive envi¬ 
ronment. Easy to use, RDC 
enhances your code writing abil¬ 
ity while increasing productivity. 
Programs are debugged easily 
and quickly! 

• Supports Multiple 
Platforms 

• Source Code Display 

• Variable Display Service 

• Variable Alteration 

• Single Step Review 

• Dynamic Watch 
Windows 

• Logic Alteration 

• Deferred Debug Option 



Call 

800 - 724-7011 



Suitable 

Alternatives 


4655 Old Ironsides Drive, Suite 220 
Santa Clam, CA 95054 • 408-727- 
3142 




its title and folder and then set an 
ObjectID for that specific object. With 
the ObjectID set, even Classic REXX 
can manipulate the object 

The most complex part of the 
program is the actual parsing of the 
parameters for the different possible 
scenarios. Some of the complexity is 
due to the way ypfind.cmd looks for its 
parameters. As you can see from the 
code, if an object is nested within sev¬ 
eral folders, wpfind wants a path of ti¬ 
tles for those folders starting with the 
first folder on the desktop. One possi¬ 
ble change to the 'wpfind.cmd' is to 
make it accept parameters in a little 
more straightforward fashion; it 
would first ask for the title of the ob¬ 
ject and then for the folder where the 
object is. 

Note that I've used methods 
wherever I could, even in the parsing 
and verification of the parameters. 
Object REXX allows you to use either 
the built-in functions you are used to 
or the built-in methods. 

Once the parameters are parsed, 
the rest of the program is fairly easy. 
Before setting the ObjectID, the 
wpQueryObjectID method is called. This 
is to get a confirmation from the user 
that if a current ObjectID already ex¬ 
ists, it should be overwritten. 

One interesting thing with the 
SETOBJID program is that it could be 
written, or at least tested, in just two 
lines! I first experimented with the ca¬ 
pability with two commands using 
REXXTRY; 

ofa j=ypf ind ("Internet 1 ') 

obj " u ps etu p (" OBJ ECTCD= ?T estOb j ec tID > 11 ) 

One other note is that multiline 
titles will cause problems. This is be¬ 
cause there is a linefeed character (hex 
'GA') in the title. Tve left it as an exer¬ 
cise for the reader to add this logic 
(which really means I'm running out 
of time and space), 

OTHER COOL WINGS TO DO 
fMWITH OBJREXXAND WPS 

The surface of what Object REXX can 
do has barely been scratched, even 
when talking about just the limited 
scope of using Object REXX to work 
with the WPS! One cool thing to try 
when you get your version of Object 
REXX going is to start up a session of 
REXXTRY, Then get out your WFS 
reference documentation, which 
comes on the Developer's Connection 
as INF files (WFS1+WPS2+WFS3). 
Spin through some different methods, 
such as wpQuerylconTitle, ypQpen, and 


ypQueryQbjectld and see how easy it is 
to manipulate WPS objects—there's 
no quicker way to learn the WPS. 

Another huge topic that has not 
even been touched on is the ability of 
Object REXX to actually subclass 
SOM and WPS objects. Yes, it will 
work. You can create REXX classes 
that are subclassed from SOM WPS 
classes. Once that is done, you can 
override the inherited methods to 
make the WPS object behave the way 
you want it to. The traditional exam¬ 
ple (funny how "traditional" in this 
industry is one- or two-year-old tech¬ 
niques) is to create a password-pro¬ 
tected folder by subclassing tfPFolder 
and overriding upOpen with the logic to 
open the folder only after a valid 
password has been entered. The 
Object REXX developers are provid¬ 
ing an example that will be doing just 
that with the Object REXX code on the 
Developers Connection 7 CD-ROM. 

Bret Curran is an independent 0&2 systems 
consultant specializing i in assisting corpora - 
tions install configure, and manage wge 
OS/2 networks , He was previously the OS/2 
team leader in IBM's Personal Systems 
Competency Center in Dallas t Tex . He has a 
bachelor's and master s degree in Information 
Systems from the University of North Texas . 
You can reach Bret at curranb@ihm.net or 
817/382-2362 
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JREXXO.INF) in Object REXX 
WPS References (WPSMNF) in 
OS/2 Toolkit 

The Object REXX code can be 
found on the Developers Con¬ 
nection CD-ROM, beginning with 
DevCon 6. This article and sample 
code are available on Compu¬ 
Serve's OS2DF2 Forum, OS/2 
Developer section. Download file 
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Thanks to the entire Object REXX 
development team for creating 
such a cool and powerful lan¬ 
guage! 

Thanks especially to Steve Pritko 
and Rick McGuire for the help he 
provided, both knowingly and un** 
knowingly. 
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A well-designed program is the most effective way to gain performance improvements. 
But sometimes code tuning is the only practical way to do it. These tips and techniques 
should help. 

By CRAIG HODGINS 





Six Simple Code- 
Tuning Techniques 


C ode tuning is not necessarily the best 
method to improve program perfor¬ 
mance. In fact, it is often viewed as a 
very negative thing to inflict upon any pro¬ 
gram. For example, in Steve McConnell's 
Code Complete: A Practical Handbook of 
Software Construction , Donald Knuth says, 
"We should forget about small efficiencies, 
say about 97% of the time: premature opti¬ 
mization is the root of all evil." 

A well-designed program is a more ef¬ 
fective way to gain performance improve¬ 
ments. Good data structure and algorithm 
selections also bring better results. Buying 
new hardware or a better compiler is an eas¬ 
ier way to improve performance. But some¬ 
times code tuning is the only practical way 
to improve substandard performance, espe¬ 
cially when using REXX, which is for the 
most part an interpreted language. 

The Pareto Principle, commonly known 
as the 80/20 rule, applies to program opti¬ 
mization, as well as other areas of life. This 



Figure 1A. Unswitching. 


principle states that you can get 80% of the 
result with only 20% of the effort. As docu¬ 
mented in McConnell's handbook, Barry 
Boehm found that 20% of a program's rou¬ 
tines consume 80% of its execution time. 
Knuth discovered that less than 4% of a pro¬ 
gram usually accounts for more than 50% of 
its run time. 

What this means is that very often small 
snippets of code, often overlooked by pro¬ 
grammers, can be costly in performance. 
Programmers must identify those small 
parts of the program that are causing the 
performance degradation. The performance 
can be measured, the hot spots identified 
and optimized, and the performance mea¬ 
sured again to see if an improvement occurs. 

The measurements must be precise and 
consistently applied. A simple way to do this 
in REXX is to use the language itself. See "A 
Simple Performance Analyzer" for a discus- 



Figure IB. Unswitching. 
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sion of a simple performance analyzer 
tool. 

Once a hot spot has been identi¬ 
fied, how do the programmers go 
about improving performance? Many 
code-tuning techniques are based on 
established programming principles. 


What follows are six of the most com¬ 
mon and simplest techniques and how 
they can be applied while using the 
REXX language* 

Please note that the code examples 
shown are for illustration purposes 
only and do not necessarily represent 


nun * 10000 
x = time('E') 
do i * 1 to hub 

CustOBerliame.i * ' ' 

end 

do i ■ 1 to nm 

balance.i * 0 

end 

say '*** Elapsed tune: ' timet'E') 

nura - 10000 
* = tinteCE'} 
do i = 1 to nunr 

CustoBefName.i = ' ? 

balance.! = 0 

end 

say '*** Elapsed tune: ' tifie('E') 

Figure 2A. Jamming. 

Figure 2B , Jamming, 

hub - 20000 

num = 20000 

i * 1 

index = 0 

* = ti»e('E-) 

i = 1 

do while (i <= nuni) 

x = timet'E') 

anyvar.i = i 

do while (i < mm] 

i - i + 1 

anywar.i = i 

end 

index *1 + 1 

say '*** Elapsed time: ' timef'E*) 

anyvar.index - i + 1 


i = i + 2 


end 


if i = nun then anyvar.nuB = nm 


say Elapsed time: 4 timet'E') 

figure 3A. Unrolling. 

Figure 3B. Unrolling . 


A Simple Performance Analyzer 


You don't have to spend a lot of money to get a good performance analyzer. REXX 
comes with a TINE function that can be effectively adapted to provide a simple yet use¬ 
ful performance tool. The benchmarks used in this article were all calculated using this 
technique 

The TINE function by default returns the local time. Various options may be used to 
obtain alternative formats or gain access to the elapsed time clock. HNE('R') returns 
the number of seconds and microseconds since the elapsed time clock was started or 
reset ft also resets the elapsed time clock to zero. TINE( "V) returns the number of 
seconds and microseconds since the elapsed time dock was started or reset, 

The TINE function can be used for measuring real elapsed time intervals. The first calf 
to either TINE (*r) orimVD will return 0 Thereafter, the elapsed time since the 
first call or since the last call to UME( 'R') will be returned 

To find the hot spots in your REXX program, insert TINE calls at strategic places 
throughout the code, making sure to label them appropriately so you can match the 
times with what is being measured In this way, you have a reliable, consistent mea¬ 
surement with which to make your benchmarks. The benchmarks for this article were 
evaluated by inserting TIME(T) statements at the beginning and end of the code to be 
analyzed, along with a SAY statement to write the elapsed time to the screen 

For the most accurate results, do the benchmarking in isolation from any other corn* 
puter functions. In oilier words, do not have any other system tasks or programs run¬ 
ning while you are analyzing the performance of your REXX program. Other tasks and 
programs may take up clock time and corrupt your benchmark results. 


practical logic constructs. In fact, some 
of them may appear trivial. However, 
they do illustrate the code-tuning prin¬ 
ciples under discussion. The loop 
counters may also seem exaggerated in 
some instances, but remember that in a 
real application, thousands of itera¬ 
tions may be involved, and the point is 
to show how a small change in the 
code can affect elapsed time. 

SiXCODE-TUNING TECHNIQUES 

Unswitching. Unswitching turns a loop 
inside out. A switched loop makes a 
decision every time it is executed 
(Figure 1A). Since the decision doesn't 
change as a result of the looping going 
on around it, you can unswitch the 
loop by moving the decision outside 
the loop* Basically, unswitching is 
putting loops inside the conditional 
rather than putting the conditional in¬ 
side the loop. 

In Figure 1A, the loop is executed 
Nuro times. The Flag variable is tested 
inside the loop, and different branches 
are taken accordingly. In Figure IB, the 
Flag variable is tested outside the loop, 
and the appropriate loop is executed 
as a result of the test. By moving the 
test outside the loop, a performance 
improvement of 33% occurs. 

Jamming. Also known as fusion, 
this technique combines two loops 
that operate on the same set of ele¬ 
ments* Figure 2A shows two loops 
that are candidates for jamming be¬ 
cause they are both executed Hum times 
and contain arrays of the same num¬ 
ber of elements. 

Figure 2B shows the jammed {or 
fused) loop. The performance gain 
comes from cutting loop overhead; 
you have exactly one-half the number 
of loops as before, with the same re¬ 
sulting function* Note that the perfor¬ 
mance is not cut in half, as might be 
expected. This shows the importance 
of actually measuring performance re¬ 
sults, rather than assuming what 
might happen. 

Unrolling * Similar to jamming, un¬ 
rolling reduces loop housekeeping, but 
in this instance by handling two or 
more cases in each pass through the 
loop* Figure 3A shows a While loop 
that can be unrolled. In Figure 3B, the 
loop has been unrolled once; that is, 
two assignments are done in the loop 
and the loop counter is incremented by 
two, instead of one. The loop could be 
unrolled three times, four times, or 
more. 

Be warned, however, that un¬ 
rolling costs heavily in readability and 
maintainability* You can see that un- 
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rolling the loop just once adds more 
lines of code and more logic than the 
original. Also, code must be added to 
cover special cases, since the counter is 
incremented by two instead of one. 

Sentinel Values. In this article, a 
sentinel value is a variation of the clas¬ 
sical sentinel value concept. In the clas¬ 
sical case, a loop has a compound test; 
for example, a search loop that tests 
whether a match has been found and 
also whether or not the search list has 
been exhausted. The code tuning is 
achieved by inserting a test value at 
the end of the search list and then 
changing the loop conditional to test 
whether or not the current search ele¬ 
ment equals the test value. 

While the conditional is not equal, 
the loop increments; when it is equal, 
the loop is terminated. Because of this 
earlier termination, processing time is 
reduced. 

The variant sentinel value dis¬ 
cussed here is based on a similar idea. 
In our case, a test value is assigned, 
and the conditional checks whether the 
current array element is equal to the 
test value. If not, the loop is incre¬ 
mented; if so, the loop terminates im¬ 
mediately, because the matching value 
has been found. 

Other code goes with the sentinel 
value sample. For example, for Figure 
4A an If Found = Yes statement group 
is needed to determine whether the 
test value actually was found. In 
Figure 4B, the code would be similar to 
an If (i < maxcount) group. 

For our example, the test value 
variable is arbitrarily set at 7777 in an 
array of 10000 for consistency. As the 
test value changes, the elapsed time 
would change also; however, the time 
savings would still be achieved by 
using the sentinel value. 

Busy Loops Inside. When loops are 
nested, such as in Figure 5A, care must 
be taken as to which loop to place on 
the inside. This loop loads a two-di¬ 
mensional table with random num¬ 
bers. The table has five rows and 100 
columns. With the busiest loop on the 
outside, the performance is not bad. 

However, when the busiest loop is 
placed on the inside, the performance 
improves 20%. On every iteration, a 
loop has to initialize the index, incre¬ 
ment the counter, and check it. For 
Figure 5A, the total number of execu¬ 
tions is 100 for the outer loop and 500 
for the inner loop (100 x 5). This is a 
total of 600 iterations. 

Switching the loops changes the 
number of outer iterations to five and 
the number of inner iterations to 500 



Figure 4A. Sentinel value. 



Figure 5A. Busy loops inside. 



Figure 6A. Simplify tests. 



Figure 4B. Sentinel value. 



Figure 5B. Busy loops inside. 



Figure 6B. Simplify tests. 
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Figure 7. Dynamic SAY, 


Test 

Elapsed 

% Saved 

Iterations 

1A 

26.06 


100000 

IB 

17.49 

33 

100000 

2A 

6.68 


10000 

2B 

4.68 

30 

10000 

3A 

8.52 


20000 

3B 

7,83 

8 

20000 

4A 

3.08 


1O0OO 

4B 

1.93 

37 

10000 

5A 

0.25 


600 

5B 

0.20 

20 

505 

6A 

0.43 


1 

6B 

0.03 

93 

1 


Elapsed times are in seconds based on 
an average of three executions. 


Table 1 Benchmark results. 


(100 times 5). This results in 505 execu¬ 
tions instead of 600, and the resultant 
performance savings. 

Simplify Tests , Use simplified tests 
rather than more costly operations to 


A Simple Debugging Tool 


One of the best and simplest debugging tools available in REXX is the SAY statement 
As the programmer, you can place SHY statements throughout your code to issue 
explicit debug messages or see exactly what is in a variable at run time. 

However, in a large, complex program, many SAY statements may exist. Once the pro¬ 
gram is debugged and in production, the SHY statements are no longer needed—until a 
change is made and debugging is necessary again 

It can be time-consuming and frustrating to have to apply all those SAY statements 
again, especially in the right spots The following technique can be used to dynami¬ 
cally turn the SHY statements on and off with a simple switch. 

Figure 7 shows a simple use for the dynamic SHY technique, When the REXX program 
is called from an OS/2 window with the / Y parameter, the SHY statements in the pro¬ 
gram will be "turned on" and executed. If the /Y parameter is not passed, the SHY 
statements will be interpreted as comments and not executed. 

This is accomplished by using the INTERPRET statement to dynamically turn the SHY 
statement on and off. The !8D ! (begin debug) and the !£D! (end debug] control char¬ 
acters are set to either nulls or comment delimiters. When set to nulls, the SAY state¬ 
ment is executed. When set to comment delimiters, the SHY statement is interpreted as 
a comment. In this way, the SAY statements can be left in the program to be used or 
not used as required. 

This technique has two drawbacks. First you cannot use it with compiled REXX, as the 
compiler does not understand the INTERPRET statement. Second, in an interpreted envi¬ 
ronment, the INTERPRET statement uses resource, whether the SAY statements are 
turned on or off. This must be taken under consideration 

Like most thi ngs in computer science, a tradeoff exists between performance and ease- 
of-use that only the individual programmer can weigh at any given time in any given sit¬ 
uation. Regardless of the practical use, the dynamic SAY statement may have in the 
real world, it illustrates quite nicely the flexibility and power of the REXX language 
Creative programmers have no lack of opportunity with REXX 


save on performance. For example. 
Figure 6A shows a program that com¬ 
pares FOOBAR(X) and FOOBAR(Y), 
The FOOBAR internal function is in¬ 
tended to be meaningless but time 
consuming. You can substitute your 
favorite function for FOOBAR. 

Since the function acts identically 
on the arguments, any comparison 
made on the arguments will equal any 
comparison of the results returned by 
the functions* In other words, by re¬ 
placing the FOOBAR comparison with 
a simple X < Y comparison, perfor¬ 
mance is vastly improved. 

Figure 6B illustrates this simple 
improvement. The arguments X and Y 
are compared, rather than the returned 
values from the FOOBAR functions* 
The results speak for themselves. 

Sometimes programmers like to 
use the neat features of a language to 
keep code tight and compact, thereby 
sacrificing performance and, in this 
case, readability. 

SUMMARY 

Code tuning is not always the best 
way to improve performance. Per¬ 
formance should be built-in by good 
module design and correct data struc¬ 
ture and algorithm selection. But when 
tuning is required, remember these six 
simple code tuning techniques and the 
principles on which they are based. 

Craig Hodgins has worked for IBM Canada 
Ltd ,, Toronto, Ontario for 14 years in both sys¬ 
tems and application programming. Currently, he 
is a programmer/analyst working on a large 
software manufacturing system. Craig earned an 
Bachelor of Arts in History from York University 
in Toronto in 1981 Craig can be reached at (905) 
316-5858 orchodgins@vnet.ibm.com. 
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International 


REXX is an international language. Here's how to design a program that is translation- 
ready. 

By BRUCE ERIC HOGMAN 



V 


Designing REXX 
Programs for Multiple 
Languages 


oday, REXX programs can be dis¬ 
tributed around the world via the 
Internet and other media. You can 
prepare for worldwide distribution by de¬ 
signing a program to facilitate its translation 
to other national languages such as Spanish 
or German, This article addresses some de¬ 
sign considerations for translation-ready ap¬ 
plications. OS/2 REXX is not changed for 
other language versions of OS/2, other than 
translating the error messages from the 
REXX interpreter. Even though REXX func¬ 
tions such as STREAM 0 use operands that are 
English phrases such as "query exists", these 
operands remain unchanged in other lan¬ 
guage versions of OS/2. The result codes 
from functions such as STREAMO that are 
English words such as “ERROR" or "READY" re¬ 
main unchanged also. A REXX program 
written for the U.S. English version of OS/2 
will run unchanged on another language 
version of OS/2, assuming that the operat¬ 
ing system version is similar. For example, if 
you use functions unique to OS/2 Warp 
V3.G, your program will not run on eariler 
releases of the operating system that do not 
support the functions. 

OS/2 COMMAND NAMES 

Other language versions of OS/2 retain the 
U.S. version command names. This means 
you can invoke OS/2 commands by name, 
such as COPY or RENAME, within your REXX 
programs, and the program will not need to 
be changed to work with other language 
versions of OS/2. 

Messages from running OS/2 com¬ 
mands are changed, however, so your REXX 
programs cannot depend on information re¬ 
maining the same if you invoke a command 
and capture the STDPUT output. You should 
design your REXX program to interpret the 
return codes from invoked commands and 


to do additional processing to ensure the 
successful processing by OS/2 commands. 
For example, if you copy files using the COPY 
command, successful completion results in 
RC=0. It is good practice in general to test 
return codes from all commands and func¬ 
tions. Determine what return codes are pro¬ 
duced by all the commands your program 
will use by first reviewing the online OS/2 
Command Reference (VIEW CHDREF) and then 
by coding and running test REXX programs 
to invoke the commands and display the re¬ 
sulting return codes. 

EXTERNALIZING MESSAGES 

To design for national language support 
(NLS), plan to package all messages from 
your program in external data files. The 
message file can be translated into other lan¬ 
guages, with each different language identi¬ 
fied by its one- or two-character language 
identifier associated with the SYSLEVEL of 
the OS/2 system as shown in Table L 

You can save space in distributing your 
application files by using the PACK.EXE 
utility that is part of the Developer Toolkit 
to create a bundle file containing all lan¬ 
guage versions of your application files. You 
can invoke the UNPACK command that is dis¬ 
tributed with OS/2 to extract those files spe¬ 
cific to the language in use on the PC. Name 
the packed files with a common prefix and 
language-specific suffix, like MYAPP.K_0, 
NYAPP.M_F, MYAPP.M_G, where you will extract 
the file HYAPP,M_? to the hard drive and re¬ 
name it to HYAPP, MSG for use by your REXX 
program. 

If you pack files and your program will 
be run on early releases of OS/2, restrict 
yourself to the PACK.EXE program instead 
of the later PACK2.EXE so that the user can 
run UNPACK successfully. Refer to the 
Developer's Toolkit online documentation 
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1 OS/2 country name 

2 OS/2 keyboard name 

3 OS/2 countrycode (3 num) (CONFIG.SYS) 

4 OS 12 codepage (3+3 or 3) {CONFIG.SYS) 

5 OS/2 keyboard code (5 char) (CONFIG.SYS) 

6 OS/2 Syslevel 3rd char (1 char) 


1 

2 

3 

4 

5 

6 

Brazil 

Brazilian 

055 

850,437 

BR 

B 

Canada 

Canadian French 

002 

850,863 

CF 

C 

(French) 

Denmark 

Danish 

045 

850 

DK 

D 

Finland 

Finnish 

358 

850,437 

SU 

L 

France 

French (189) 

033 

850,437 

FR189 

F 

Germany 

German 

049 

850,437 

GR 

G 

Italy 

Italian (141) 

039 

850,437 

ITT 41 

I 

Netherlands 

Dutch 

031 

850,437 

NL 

H 

Norway 

Norwegian 

047 

850 

NO 

N 

Portugal 

Portuguese 

351 

850,860 

PO 

P 

Spain 

Spanish 

034 

850,437 

SP 

S 

Sweden 

Swedish 

046 

850,437 

SV 

W 

U.K 

U.K. 

044 

850,437 

UK 166 

U 

US, 

U.S. 

001 

437,850 

US 

0 


Table 1. Language and country codes. 


softcopy for full informationon the use 
of the PACK utility. 

Include in your program initial¬ 
ization code to load the message file 
into a stem variable at the start of your 
program, to permit fast access to the 
data. Use code similar to that included 
below: 

/* load massages from external file */ 

/* make stem variable "message.” all null 

*/ 

message, = " 
msgfile * 'MVAPP,H5G 
do while lines(msgfile) > 0 
xstr = linein(msgfile) 

/* extract the message identifier */ 
msgid = left(xstr,7) 

/* id and text into stem variable */ 

message,msgid = xstr 

end 

/* close the input file */ 
call stream msgfile,'c%'dose' 

In the above block of code, the 
messages are addressed using their 
message identifier, the three-letter 
prefix, and four-digit suffix. The mes¬ 
sage identifier and text for message 
MYAOQ10 is in variable message.msgid 
when msgid = 'WYAQQIOL Display both 
the message identifier and the mes¬ 
sage text to the user. This helps sup¬ 
port staff to resolve problems by iden¬ 
tifying the message clearly. Avoid 
using a single message for more than 
one logical function. This helps to 


identify the code in your program 
that issued the message. Some mes¬ 
sages, such as generic data display, 
could be reused. 

The \os2\install\sjslevel,os2 file, 
byte 47, is the single-character lan¬ 
guage code that indicates the lan¬ 
guage version of OS/2 installed on 
the personal computer. The IBM ex¬ 
ternal function package RXUTILS, 
available on IBM BBS, IBM inter¬ 
nal VM OS2TOOLS, and other 
sources has a function, RXSYSLEVEL, 
that returns the SYSLEVEL value and 
associated identifying text. Review 
the details on that function in the 
RXUTILS.1NF file. 

The following REXX code, when 
created as SYSVALU.CMD file, can be 
used to obtain the OS/2 SYSLEVEL if 
you do not have RXUTILS function 
package: 

File SYSLVALU.CMD: 

/* SYSUALU function: given filespec of 
syslevel. 

return syslevel string */ 
arg slvlfile 

if slvlfile * '' then return " 

sdata = cha r inf slvlfile f , chars (slvlfile)) 

call stream slvlfile/c', 'dose' 

/* extract the syslevel and text */ 
return substr(sdata,45,post'GO'x,sdata, 
45)) 

In another REXX program, re¬ 


trieve the SYSLEVEL.OS2 value by 
using the following code: 

bootdrive * left(value('COHSPEC ',/ 
0S2ENYIR0NMENT'),2) 

/* invoke syslvalu.cmd as external 
function (must be in PATH) */ 
syslevel = 'SYSLMUF (bootdrive'\as2\ 
install\sy slevel, os2') 
lang_code = substr(syslevel,!,!) 

FORMA T OF MESSAGE FILE 

Your message file should have a for¬ 
mat similar to that shown below: 

mnnnnS TTTTTT %1 TTTTTT 7,2 TTTTTTTTTT 

JtHnnnnS is a message identifier 
with a constant letter prefix of three 
characters, and a numeric suffix of 
four decimal digits, with a severity in¬ 
dicator letter from the following list: 

E: Error 
H: Help 
I: Information 
P: Prompt 
W: Warning 

An example line entry in your 
message file may appear as follows: 

MYA0010I: File J{1 created. 

This example follows the syntax 
requirements of the Developer's 
Toolkit message file utility input text 
file. If you use the same message file 
format, then your message file could 
later be used if you convert your 
REXX program into a compiled lan¬ 
guage program. In any case, your 
messages would appear similar to 
those displayed by IBM programs, 
and all your messages would have a 
common appearance. Your REXX code 
can read in the message file as a text 
file. 

The percent sign and number in 
the above message example indicate a 
text insertion into the message text, 
where an argument passed to your 
message displays procedure or func¬ 
tion substitutes for the text insertion 
tag. Let's assume you name your mes¬ 
sage display procedure Display^Hessage:, 
then you would retrieve message text 
using code similar to that below: 

msgtext = Display ^Message!'HYAOOKT, 
created_file) 

You could then use the SAY key¬ 
word to display the message text or 
log the text to a hie. The Display_Message 
procedure would read the message 
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file or table, addressing the message, 
stem variable similar to the code 
shown here: 

Display.Message: procedure expose 
message* /* input: 7-char message 
identifier 

plus optional 1-9 text arguments: 
msgid,insertl,insert2,insert^ *** 
returns: message text tfith insertions */ 

/* obtain message identifier argument */ 
parse arg msgid,other 
i* make identifier upper case */ 
msgid = translate(msgid) 

/* get text of message entry */ 

xstr = message.msgid 

/* get position of 7/ in text */ 

fci = pos{ 7/jXstr) 

do while ki > 0 

inum = substr(xstr,ki+l,l) 

if datatype (ilium ,'ir') £ , 

(inum > 0 fc inum < 10) then 
do 

if ki > 1 then lstr = left(x$tr,ki-l) 
else lstr = " 

/* code assumes only 1 digit for number 
*/ 

rstr = substr(xstr>ki+2) 
inum ■ substr(xstr,ki+l,l) 

/* start with arg(2), which is the first 

text insertion */ 

xstr = lstr||arg(inum+l)||rstr 

/* find next insert or end loop */ 

ki = pos(7%xstr) 

end 

else ki = 0 /* end loop */ 
end 

return xstr 

The procedure code would also 
obtain the text for message MYA0010, 
parse the text, and substitute the 
string contained in the variable cre- 
ated_file for the text insertion string 
XL The resulting message shown to 
the user would be similar to: 

MY 100101: File c:\myapp\newtext.txt 
created* 

DESIGNING USER RESPONSES 

Avoid words or letters as responses to 
prompts to the user for input, This 
pertains to responses on which your 
program will base further processing. 
You can ask the user for responses 
that are character strings that do not 
need translation, such as path or file 
names* Otherwise, you can display a 
list of choices to the user and accept a 
number corresponding to one of the 
available listed choices when the user 
must choose among processing alter¬ 
natives. 

If you display several lists of 
choices during your program, and 


there are similar choices listed, try to 
keep the order of the choices the same 
for each displayed list. This helps to 
minimize user confusion when read¬ 
ing the list. If you provide a default 
choice, that choice should be the one 
the user would be most likely to select 
in normal processing. Any default 
choices should follow the general 
principle of systems design: that a de¬ 
fault action results in the minimum 
change to the system data. Keep data 
if it existed before your program, for 
example. 

Take some time to design re¬ 
sponse formats carefully when dealing 
with dates or time of day* Remember 
that other countries use different date 
and time formats. You can access the 
OS/2 country information using the 
REHUTIL SYSINIO function call to read 
the PM_National application and its 
corresponding keys. Review the docu¬ 
mentation on the SYSINIO function in 
the REXX.1NF online softcopy. 

The iOate key indicates the date 
format, and iTinie key the time format* 
Your prompt messages should include 
an example of how to format the re¬ 
sponse by displaying the current date 
or time using the OS/2 PMJMational 
formats chosen by the user. The code 
examples listed below show you how 
to access this data. 

Obtaining the iTime format: 

iDate * sysini/user','PM_National% 
'iDate'} 

/* values are: 0,1,2: n/d/y, d/m/y t 
y/m/d */ 

Obtaining the sDate separator 
character: 

sDate = sysini/ user VPM .National/, 

*sDate') 

/* single character, like or 7' 
for m-d-y or ni/d/y */ 

Obtaining the iTime format: 

iTJjne = $y$iju('user% 'PM. National', 
'iTi/ne') 

/* values are: 0, 1: 12-hr, 24-hr */ 


character (which is a comma in 
European countries), thousands sepa¬ 
rator, and so on, including the country 
code itself. 

The following code displays the 
list of defined keys for PM_National: 



/* display ini keys for PH_National */ 
call sysini 'user'/PM. National', 
'allr'/pmkeys/ 
say '0S2.INI PM.National keys' 
do j = 1 to pmkeys.Q 
key value = sysini( 'user' /PM.National', 
pmkeys.j) 

say copies/ ',3) | Ipmkeys. 

j||' s '(|keyvalue 
end 


ADVANCED CONCEPTS IN 
LANGUAGE SUPPORT 

REXX programs can handle languages 
with double-byte character sets 
(DBCS) if you use the statement below 
to tell the REXX interpreter you will 
be using DBCS strings: 

OPTIONS ETMQDE' 'EXMODE' 

If used, OPTIONS should be the first 
statement in your REXX program 
sothe interpreter can process your 
program correctly. 

Handling right to left (RTL) lan¬ 
guages such as Hebrew and Arabic 
can be done on a version of OS/2 not 
equipped to process RTL if you write 
functions to display message text in 
RTL mode* Presenting non-RTL data 
within RTL messages requires discus¬ 
sion of RTL languages that is beyond 
the intended scope of this article* 

SUMMARY 

Writing REXX programs for several 
language versions of OS/2 is easier 
using the concepts presented in this 
article* Several of the topics apply to 
REXX programs in general, such as 
the proper use of system settings se¬ 
lected by the PC user* Users will ac¬ 
cept your applications much more 
readily if they find that it recognizes 
their personal system setting prefer¬ 
ences, and your applications may find 
acceptance in several languages when 
you build in language support 


Obtaining the sTime separator 
character: 

sTijne = sysini/user'/PM.National', 
'sTime') 

/* single character, like ':' 
for hh:mm:ss */ 

The application has other keys for 
list separator character, decimal point 
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Objects 


The OS/2 Workplace Shell provides a 32-bit, SOM-based interface. Here are more tips 
and techniques for exploiting it from your REXX programs. 

By RONY G. FLATSCHER 


The Workplace Shell: 
Objects to the Core 


r he design of the OS/2 Workplace 
Shell (WPS) makes it possible for 
REXX programs to interact directly 
with it. The steps necessary to successfully 
create, change, open, and delete Workplace 
Shell objects with REXX are explained here 
using sample REXX programs. After reading 
this article, you should be able to write your 
own REXX programs for manipulating 
Workplace Shell objects. 

The 32-bit versions of OS/2 include a 
user interface based on the ground-breaking 
System Object Model (SOM) technology: the 
Workplace Shell. Some simple interfaces to 
the WPS have been supplied for REXX via 
the RexxUtil.DLL. In order to utilize this inter¬ 
face and understand our examples, a basic 
understanding of the WPS is necessary. 

The Workplace Shell is built on a SOM- 
based class hierarchy called 'The Workplace 
Object Class Hierarchy" (Figure 1). The root 


of all of WPS object classes in SOM is clearly 
visible, as the class WPObject is an immediate 
descendant of the abstract SOMObject class. 
Abstract classes are not meant for producing 
objects directly from them, but instead for 
ordering properties in a structured, hierar¬ 
chical manner. Hence, abstract classes are 
used as a base for more refined classes and 
usually implement general properties found 
in all descendants. 

Due to the object-oriented technology in 
WPS, every object class in its hierarchy in¬ 
herits all capabilities of its ancestors, refines 
them, and may add additional properties. A 
programmer simply asks for an instance of a 
nonabstract class and gets a fully functional 
object in return, one which incoporates all 
the capabilities of the class and its ancestors. 

SET-UP STRING INTERFACE 

Some WPS classes allow for a very simple 


SOMObject 


SOMClass 


SOMCIassMgr 

** WPObject 

WP Abstract 


WPCIock 


WPCountry 

* WPDisk 
WPKeyboard 

* WPLaunchPad 
WPMouse 

* WPPalette 



* WPColorPalette 

* WPFontPalette 

* WPSchemePalette 
WPPower 

* WPPrinter 

* WPRPrinter 


a 


** WPProgram 
** WPShadow 
WPNetLink 
WPShredder 
WPSound 
WPSpecialNeeds 
WPSpool 
WPSystem 
WPWinConfig 
WPFileSystem 
WPDataFile 
WPBitmap 
WPIcon 
WPMet 
WPPif 
WPPointer 
* WPProgramFile 
WPCommandFile 


f WPFolder 
WPDesktop 
WPDrives 
WPMinWinViewer 
WPNetgrp 
WPNetwork 
WPRootFolder 
* WPServer 
WPSharedDir 
WPStartup 
WPTemplates 
WPTransient 
WPJob 
WPPdr 
WPPort 
WPQdr 


Figure 1. The workplace object class hierarchy. 
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(and therefore very clever) in¬ 
terface: the setup string inter¬ 
face. The string interface con¬ 
sists of pairs of keywords and 
string values delimited always 
with a semicolon (;)* Sending 
such strings to objects of the 
WPS object class hierarchy af¬ 
fects the state of those objects 
and is thereby a valid means of 
communication. Because the 
user interface is so important 
to OS/2, some procedural in¬ 
terfaces to WPS objects have 
been implemented, such as 
iinSetObjectDataO, to allow 
sending setup strings to them. 
Some of those Win-API inter¬ 
faces are available through the 
Rex x UH1* DLL. 

Figure 1 depicts classes 
with a string interface by a 
leading asterisk* Because the 
root of the WPS-tree, the ab¬ 
stract class VP Object, contains a 
string interface itself, all WPS 
classes contain a string inter¬ 
face. So the word "some" in 
the very first sentence of this 
subsection has to be changed 
to "all WPS-dasses.,.". This is 
an immediate consequence of 
the basic inheritance property 
of object-oriented systems. 
Some classes, like VPDisk add 
additional strings, that is, new 
keywords for setup strings, or 
they may alter the meaning of 
some setup keywords* 

Valid keywords, their 
proper values and their mean¬ 
ings, are explained in IBM's 
WPS documentation on the 
Developer Connection CD- 
ROM* An overview of the vari¬ 
ous object classes is also pro¬ 
vided* The keywords and 
values for the WPS object 
classes used in our REXX ex¬ 
amples are included in this ar¬ 
ticle and are indicated with two 
leading asterisks in Figure 1. 

Most keywords are found 
in the object class WPObject, 
(Figure 2)* Much interesting in¬ 
formation can be stored with 
WPS objects. For example, the 


KEYNAME 

VALUES 

REMARKS 

CCV1EU 

DEFAULT, YES, NO 

Create new view on user 
open ? 

DEFAULTVIEW 

SETTINGS, DEFAULT, id 

Set defautlview on user open. 

HELFLIBRARY 

filename 

Set the help library. 

HELPPANEL 

id 

Set help id. 

HIDEBUTTON 

YES, NO 

Use hide-button on window? 

ICONFILE 

filename 

Set icon. 

ICONPOS 


Set icon position in folder in 
percent coordinates* 

ICONRESOURCE 

id,module 

Set DLL and icon ID within. 

HINWIN 

HIDE, VIEWER, DESKTOP 

Determine where to 
minimize. 

NOCOPY 

YES, NO 

Copy of object not allowed? 

NODELETE 

YES, NO 

Deletion of object not 
allowed? 

NODRAG 

YES, NO 

Dragging of object not 
allowed? 

NODROP 

YES, NO 

Dropping on object not 
allowed? 

NOLINK 

YES, NO 

Creating links of object not 
allowed? 

NOMOVE 

YES, NO 

Moving of object not 
allowed? 

NOPRINT 

YES, NO 

Printing of object not 
allowed? 

NORENAME 

YES, NO 

Renaming of object not 
allowed? 

NOSETTINGS 

YES, NO 

Opening of settings page not 
allowed? 

NOSHADOW 

YES, NO 

Same as NOLINK 

NOTVISIBLE 

YES, NO 

Object not visible on 
desktop? 


Figure 2, The setup string parameters for WPObject. (Continued on page 44J 
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key NODELETE determines whether 
or not a specific object can be deleted, 
depending on whether it is YES or NO. 
The key OBJECTID provides a user- 
defined unique identity for each object, 
and that string must be enclosed be¬ 
tween brackets: "<" and 

FORMA TTING OF SETUP STRINGS 

A setup string contains a keyword, im¬ 
mediately followed by an equal sign 
{=), then followed by the value(s), and 
then the mandatory semicolon <;) that 
Figure 2. The setup string parameters for WPObject (Continued from page 43.) concludes a key w ord / value pair. 

Usually, if a keyword accepts a list of 
values, those values are delimited by a 
simple comma Q* 

Tn the case that you need to use 
the special characters comma or semi¬ 
colon as part of a string value, you 
need to escape them with a caret ( A ), 
such as "V or 

As a rule, the values are always 
interpreted by the objects themselves 
(methods defined for that object class), 
depending on the keywords with 
which they occur. 

To learn even more about setup 
strings, one could take a look into the 
ASCII files named \Q$2\*.rc and 
\0S2\INSTALL\**rc on the boot drive, 
which the OS/2 install program uses 
to create the initial desktop. As a mat¬ 
ter of fact, you should be able to write 
a REXX program that uses these files 
to recreate the standard desktop after 
reading this article. 


Figure 3. The REXX WPS interface functions are passthrus of their corresponding Win-API-calfs. INTERACTING WITH THE WPS 

In order to use WPS REXX functions, 
you need to load them from OS/2's 
REHUTILDLL It is a good idea to have all 
of the REXXUTIL functions available 
at all times, as they provide many use¬ 
ful interfaces to OS/2 specifics. 

The REXX interface functions for 
interacting with the OS/2 Warp WPS 
are listed in Figure 3. The REXX func¬ 
tions used in these examples are de¬ 
noted by a leading asterisk. 

QUERYING INSTALLED 
WPS OBJECT CLASSES 

WPS object classes are implemented in 
the form of DLLs. Anyone can add 
new WPS object classes or even replace 
the existing ones. Figure 4 demon¬ 
strates the use of SysQueryCLassList to 
query all installed WPS object classes. 

First, the program checks to see 
whether the REXXUTIL functions are 
already loaded and loads them if nec¬ 
essary* Then, the result of the 
SysQueryClassList gets stored into a 
REXX-array with the supplied stem bv 
Figure 4, Querying installed WPS object classes. (Continued on page 45J the name Q f objQs. All entries get 


/* WPSJJCL5.CRD: query and display installed WPS object classes 

V 

/* load 05/2's Ren Util functions, if not loaded already 

IF RxFundJuery('SysLoadFuncs') THEN 

00 

CALL RxFuncAdd '$y$l_oadFuncs% *Re*xUtil% 'SysLoadFuncs* 

CALL SysLoadFuncs 

m 

*/ 

CALL SysQueryQassList “ObjQs." /* get a list of object classes 

*/ 

CALL sort /* sort in alphabetic order 

SAY "The following WPS object classes are installed 

DO i = 1 TO ObjQs.0 

PARSE VAR ObjQs.i classname classDLL 

SAY RIGHTU, 4) LEFTCdassnsme 1 ' ", 35, V) classDLL 

END 

Em 

*/ 

/* one of Knuth's algorithms; sort object classes in stem ObjQs* 
SORT; PROCEDURE EXPOSE ObjQs* 

*/ 

K = 1 /* define M for passes 

DD WHILE (9 * H * 4) < ObjQs.0 

n - ft * 3 +1 

END 

*/ 


REXX-FUNCTION 

Wm»-APt-CALl 

Querying, installing and removing WPS object classes: 

SysQueryClassList 

WinEnumObjectClasses() 

SysRegiste rObjeetCLass 

HinRegisterObj ectCLass() 

$y sDeregist er Qbj ec t Qa ss 

WinDe registe r 0 b j ectda s s {) 

Creating, manipulating, deleting WPS objects: 

SysCopyDbject 

UinCopyObjectO 

* SysCreateObject 

WinCreateObjectO 

SysCreateShadow 

WinCreateShadowO 

* SysDestroyObject 

WinDestroyObject0 

* SysKoveGbject 

WinHoveObjectf) 

SysQpenObject 

WinQpenObjectO 

SysSaveQbject 

WinSaveObjectO 

* SysSetObjectData 

WinSetObjectDataO 


OBJECTID 

<name> 

Any unique string precceded 
with a "<" and terminated 
with a ">"* 

OPEN 

SETTINGS, DEFAULT 

Opening settings view or 
default view* 

TEMPLATE 

yes, m 

Object is a template? 

TITLE 

Title 

Set title of the object. 
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DO WHILE H > 0 /* sort stem 

K = Dbjds.O - H 

DO J = 1 TO K 

Q = J 

DO WHILE q > 0 

L = q + H 

*/ 

/* make comparisons c3$e-independent 

IF TRAHSUTECQbjQs.Q) «= TRANSUTE(DbjCls.L) THEN 
LEAVE 

*f 

tmp - DbjOs.q l* snitch elements 

Objds*Q - ObjCLs.L 

QbjCLsA * tmp 

Q "Q-M 

END 

END 

n = R X 3 

END 

RETURN 



Figure 4 r Querying installed WPS object classes. (Continued from page 44J 


/* WPS.IIDEL.CND: make all WPS-default objects non-deletable 

*/ 

/* query all WPS-08 J ECHO'S (0S2.INI, app; " PH J/orkplace:Location") */ 

CALL Syslni "USER”, "PKJorkplace: Location", "ALL:", "object J.d n 

leadiiLstring = "<W*L" /* work on WPS-objects only 

*/ 

setup = "NDDELETE=VES;" /* setup string: change to not deleteble */ 

SAY "Trying to make all WPS-objects non-deletable:"; SAY 


DD i = i TD object.id.O /* loop over all entries 

*/ 

IF AB8REV(object_id.i, leadin.string) THEN /* WPS-0BJECT1D ? 
DO 

*/ 

ok = SysSetDbjectData(object^id*i, setup) /* change state 

SAY LEFT(objected*i II " ", 57, V) WQRKED(ok) 

END 

END 

*/ 

EIIT h end of program 

*/ 

/* procedure to indicate successful/net successful 

WORKED: PROCEDURE 

IF ARG(l) THEN RETURN "successful," 

ELSE RETURN "*** NOT succesful ***" 

*/ 


Figure 5 L Making default WPS objects nondeletabfe. 


sorted into ascending order and then 
the WPS object class name gets parsed 
from the DLL filename from which 
that object class is implemented. The 
output is formatted for easier reading. 

MAKING ALL WPS-DEFAULT 
OBJECTS NONDELETABLE 

When the WPS gets installed, there are 
many default folders and objects cre¬ 
ated on the desktop, such as the sys¬ 
tem folder, the enhanced EPM editor, 
and so forth. Look at the file 
\QS2\INI.RC, which drives this setup* 

All of these standard WPS-objects 
get a unique OBJECTED, which starts 
with the string <WP_. An OBJECTID is a 


string starting with a < and ending 
with a >, Knowing the OBJECTID of an 
object lets you directly set its proper¬ 
ties, delete it, move it, and produce 
links (shadows) of it. All user-defined 
OBJECTIDs of the WPS are stored in the 
0S2.INI file with the application name 
PM_Vorkplace:Location. 

Be aware though, that it is possi¬ 
ble to create objects without an ex¬ 
plicit, user-defined OBJECTID. In such 
cases, one cannot get a handle to the 
object from within REXX. 

Figure 5 first gets all known user- 
defined OBJECTIDs by using the REXXUtil 
function Syslni to access the DS2-INI 
file, including all entries stored with 
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h VPS.HTL.CHD: show setting a title 

./ 

/* setting a title with SysCreateQbject 

*/ 

title = "This is a title,"this is the second line;"this the third !' 

objectid = "<RGF Testfolder for title*' 1 

setup.string = 'ICON P0S=15,30-OBJECTID" M objectid II V 

1 

Ok - SysCreateObject("WPFoIder",, /* instance of WPFolder 

V 

title,, /* object title 


"<WP_DE$KT0P>",, /* location: desktop 

*/ 

setup.string,, /* setup string 

*/ 

"F") /* fail, if object exists 

*/ 

SAY M creating:" objectid worked (ok) 

i 

"fPAUSE" 


/* note how to escape a semi-colon which usually ends a key-value 

*/ 

setup.title * "This is a title,~this is the 2nd line"this the 3rd 

i m 

setup.string = "TITLE-" II setup.title 1! V 

ok = SysSetObjectData(objectid, setup.string) /* change title */ 

SAY "changing title:" objectid worked(ok) 

‘'epjwsp 


SAY "cleaning up..," 

ok = SysDestroyObject(objectid) /* delete folder 

SAY "destroying (deleting):" objectid worked(ok) 


Em 

f* procedure to indicate successful/not successful 

WORKED: PROCEDURE 

IF ARG(l) THEM RETURN "successful*" 

ELSE RETURN "*** NOT succesful ***" 



Figure 6. Setting an object title at creation time and with SysSetOhjectData. 



the application key PM.Workplace: 
Location, Then every OBJECTED is checked 
to see if it starts with the string <WP_. If 
it does, it uses the REUUtil function 
SysSetObjectData to change the state of 
that object to nondeletable. This is 
done by passing the setup string 
N00ELETE=YES; to the object identified by 
the 08JECTID, This property is defined 
for every single object of type VPObjeet 
(Figure 2). 

From this moment, the default 
WPS-objects cannot be deleted, and the 
delete option on the object pop-up 
menu is missing* To revert the setting, 
change the setup string to MODELETE=NO; 
and run the program again* 

SETTING THE TITLE OF AN OBJECT 

A title for a WPS object may be up to 
255 characters long at present. In the 
case where a title contains line breaks, 
this will be indicated with a caret ( A ) 
right before the intended line break in 
the setup string. 

There are two places one can de¬ 
fine a title for a WPS object with REXX; 
at object creation time (SysCreateQbject) 
and using SysSetObjectData. 

When using the TITLE keyword in 
the setup string to name the title, do 
not forget that a semicolon ends a 
key/value pair, so you need to escape 
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KEYNAME 

VALUES 

REMARKS 

AlWAYSSORT 

YES, NO 

Sort always? 

BACKGROUND 

N,H,S,B,C 

Set folder background, characters in this list represent: 


N 

Image file name. 


n 

Image mode, one of three characters: 

N (normal), T (tiled) or 

S (scaled). 


S 

Scaling factor. 


B 

Background type, one of two characters: 

I (image) or C (color only) 


C 

Background color in RGB notation. 

Example with a scaled bitmap: 

"BACKGROUNDED:\BITMAP\WARP.BMP,S,3,1" 

Example with cyan-like color background: 

BACKGR0UND=(none),„C,28 233 233" 

DEFAULTVIEW 

ICON, TREE, 

DETAILS 

Default view of container . 

DETAILSCLASS 

classname 

Set object class for details. 

DETAILSFONT 

size.font_name 

Set font for detail view (10 Helv. for example). 

DETAILSVIEW 

sl[,s2,...sn] 

Set details view' to ... (see WPS docs) 

ICONFONT 

size.font_name 

Set font for icon view (10 Helv. for example). 

ICONNFILE 

index,filename 

Set "open" icon, index is always 1. 

ICONNRESOURCE 

index,id,modname 

Set "open" icon, icon ID w ithin DLL; index is always set to 1. 

ICONVIEW 

sl[,s2,...sn] 

Set icon view styles (see below). 

ICONVIEWPOS 

x,y,cx,cy 

Initial view position and size of open folder in percentage coordinates. 

OPEN 

ICON, TREE, DETAILS, DEFAULT 

Open folder in respective view. 

REROVEFONTS 

YES, NO 

Remove instance fonts from folder? 

SORTCLASS 

classname 

Set class object to sort by. 

TREEFONT 

size.font_name 

Set font for tree view (10 Helv. for example). 

TREEVIEW 

sl[,s2,...sn] 

Set tree view styles (see below). 

WORKAREA 

YES, NO 

Set folder to be a w'orkarea? 


Figure 7. The Setup String parameters for WPFolder. (Continued on page 48.) 


the semicolon with a caret ( A ) if it is to 
appear in the title's text. Note that in 
the TITLE keyword, the comma in the 
string has no special meaning. 

Figure 6 demonstrates both sce¬ 
narios. First we have to create a WPS 
folder object from the WPFolder object 
class having the properties of any 
WPS folder. This object gets the OBJEC- 
TID <RGF Testfolder for so we can 

address it later from REXX. The icon 
for the folder gets placed 15% right 
from the left screen margin and 30% 
up from the bottom of the screen 
(IC0NP0S=15,30;). Because of the per¬ 


centage coordinates, we do not have 
to get involved with physical screen 
resolutions. 

If an object with the given OBJECTID 
exists already, SysCreateObject will fail. 
Other options would be UPDATE or RE¬ 
PLACE. If you leave the OBJECTID out of 
the setup string, the WPS will create a 
new object. 

If the user presses the return key, 
the title of this folder gets updated via 
SysSetObjectData. After another press of 
the return key, it is deleted. Compare 
the use of the caret ( A ) in the two title 
strings. 


CREATING FOLDERS , SHADOWS 
AND MOVING OBJECTS 

WPS folders gain additional setup 
strings, which are depicted in Figure 7, 
of which we will use the key ICONVIEW- 
POS in Figure 8. ICONVIEWPOS allows us to 
define a default starting location rela¬ 
tive to the lower left corner of the 
screen and, in addition, the dimension 
(width, height) of the open folder. All 
numbers are percent coordinates. 

There are two ways to create a 
shadow of an object, but both need the 
knowledge of the OBJECTID of the object 
to be shadowed: 
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FLOWED 

Flowed icon view. 

NQNFLOWED 

Non-flowed icon view. 

NONGRID 

Non-gridded icon view. 

NORMAL 

Normal size icons. 

MINI 

Small icons. 

INVISIBLE 

No icons. 

LINES 

Lines in tree view. 

NOLINES 

No lines in tree view. 


You may combine view styles by delimiting the view style values with a comma, 
For example, 'lC0NVIEW=FLOWED,MINr ; ". 


Figure 7. The Setup String parameters for WPFolder. (Continued from page 47.) 

A WPS_TSTF.CMD; test folders, shadows and moving objects 

♦/ 

/******* create four folders on the desktop to play with ************/ 

DO i = 1 TO 4 



objectid = "<RGF Testfolder." 1 i 

i || *>" A unique objectid 

*/ 

title = "Testfolder #“ i 



folder.! = objectid 

A save for later use 

*/ 

y.pos = 100 * i*20 

A placement on y-axis */ 

setup = "IC0NP0S=5," 11 y.pos || 

II, A icon placement 

*/ 

■TC0I«VIEWP0S=15," It y.pos II, /* initial folder dim: */ 

",35,20;“ 

II, /* relative to icon 

*/ 

"OBJECTION 11 objectid 11 11 ;" A assign objectid 

*/ 

ok * SysCreataQbjectf, 

A create object 

*/ 

"yPFolder",, 

A Object type: VPS-Folder 

*/ 

title,, 

A Title 

*/ 

"<UPJ>E5KTQP>\, 

A create on desktop 

*/ 

setup,, 

A setup-string 

*/ 

"F") 

A fail, if object exists 

*/ 

SAT “creating:" objectid uortced(ok) 


END 

folder.0 = 4 

A indicate 4 elements in array 

*/ 

SAY 

A display empty line 

♦/ 

f******* charge state “data to open folder in icon view **************/ 

M SPAUSE" 

DO i = 1 TO 3 

A open first three folders 

*/ 

setup = "0PEN=ICON;" 

A open them using icon view 

*/ 

ok = SysSetObjectDataCfolder.i, j 

setup) 


S1Y "setup object data ["setup 1 '] 

for" folder.! workedCok) 


END 

' 



/**♦***# create shadow of OS/2 Configuration Folder *****************/ 

shadObjID - "<RGF Testshadow_l>" 

A OBJECT'D of shadow 

*/ 

folder.5 = shadObjID 

A memorize 


folder,0 = 5 

A now we have 5 elements 

»/ 

setup * "SHAD0WID=<WP_C0NFIG>; " II, 

A shadow 0S2-config folder */ 

"OBJECTID^ || shadObjID || 

/* OBJECTID of shadow 

*/ 


Figure 8. Creating folders , a shadow and moving objects. (Continued on page 49J 
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ok - SysCreateObjectC 

A create object 

*/ 

"UPShadoH*,, 

A Object type: YP$-$hadow 

*/ 

title,, 

A Title 

*/ 

folder 

/* put into folder 1 1 

*/ 

setup,, 

/* setup-string 

*/ 

•F") 

A fail, if object exists 

*/ 

SAY "creating shadow for" folder.5 " 

worked(ok) 


SHY 

A display empty line 

*/ 

/******* Hove Testfolder # 4 between the first three folders mm**/ 

location1 = 1 

A shadow in folder #1 

*/ 

locations = 0 

A folder #4 on desktop 

*/ 

DO FOREVER 



SAY "Press enter to animate (enter 

'exit' to end):" 


PARSE UPPER PULL input 

A get input from user 

*/ 

IF LEFT(input, 1) = "E" THEM LEAVE 

A just check first letter 

*/ 

locationl = (locationl // 3) + 1 

A next folder for shadow 

*/ 

location2 = (locations // 3} + 1 

A next folder for folder # 4 

*/ 

ok = SysRoveObjecttshadObjID, folder.locationl) A move shadow */ 

SAY "moving shadow" shadObjID 11 to" 

folder.locationl worked(ok) 

ok * SysRoveObject{folder*4, folder*locations) A move folder */ 

SAY "moving folder" folder,4 "to" 

folder*location2 worked(ok) 

SAY 

/* display empty line 

*/ 

END 



/******* delete test folders ? (delete, if first letter is 11 Y" ******/ 

SAY "Delete test folders ? (Yes/tlo)" 
PARSE UPPER PULL input 

IF LEFT(inpot, 1) = T THEM 

A delete test folders ? 


DO i = folder.0 TO 1 BY -1 

A delete, start with # 5 

*/ 

ok = SysDestroyObject{folder.!) 



SAY "destroying (deleting):" folder.i worked(ok) 


END 



Em 



A procedure to indicate successful/not successful 

*/ 

WORKED: PROCEDURE 



IF ARG(l) THEM RETURN "successful. 

n 


ELSE RETURN "m NOT succesful m" 



Figure 8. Creating folders, a shadow and moving objects. (Continued frontpage 48.1 


•SysCrealeObject ("WPShadow", ,**) 
or 

•SysCreateShadow (objectid, tar- 
get_folder). 

Using the WPS object class, 
YPShadow lets us define an explicit OBJEC- 
TID for the shadow object itself* This 
WPS object class adds the keyword 
SBADOYID to the setup string, which al¬ 
lows the OBJECTID of the object to be 
shadowed assigned, 

A simpler way to achieve the 
same effect is to use SysCreateShadow, but 
in this case you cannot assign the 
shadow object an OBJECTID of your 
choice* 

Figure 8 creates four folders and 
determines the initial positions for the 
test folder icons (ICONPOS) and the posi¬ 


tion and size for opening those folders 
(ICON VIE VP OS). Using SysSetQbjectData, the 
first three folders get opened in icon 
view* Then, a shadow of the OS/2 con¬ 
figuration folder (<VP„C0NFIG>) is placed 
into the first of the open folders. By 
using SysCreateObject, it is possible to 
assign the shadow object an OBJECTID of 
its own, which we will need in order to 
move it from one open test folder to 
the next. 

The moving (animation) of the 
shadow and the fourth test folder oc¬ 
curs as long as the user presses the 
enter key: the shadow object gets 
moved to the next open test folder, as 
well as the object <RGF Testfolder_4> (ob¬ 
viously we use the function 
SysQbjectHove to move the objects). It 


may look as if the fourth test folder ob¬ 
ject chases the shadow object through 
the first three open test folders* 

Last, the shadow and test folders 
may get deleted (SysDestroy Object) from 
the WPS at the user's request. 



CREATING A CUSTOMIZED DOS 
PROGRAM FROM NOWHERE 

Our last example demonstrates 
how to define and create objects of 
type YPProgram. This object class adds 
quite a few additional setup strings 
(Figure 9). With YPProgram object classes, 
we are able to produce any type of 
program capable of running on OS/2. 
Especially for DOS and WIN-GS2 pro¬ 
grams, it is very convenient to set the 
characteristics of the virtual machines 
(virtual PCs) those programs run In* 

Figure 10 demonstrates the set up 
of a windowed virtual DOS machine 
(PROGTYPE=YINDOYEDVDH ;), running the 
DOS program \OS2\NDOS\HEH.EXE* Note 
that the keywords EXEHANE and STAR’ 
TUPDIR of YPProgram allow for substituting 
the boot drive for the string ?:\. In 
Figure 10 the EXENAME is merely a star 
(*), indicating a plain DOS-, Windows- 
or OS/2-session. In this case, the setup 
key, PRGGTYPE, determines the session 
type to be DOS; the program MEH*E)tE 
gets started because of the setup string 
P A R A MET ERS=/k mem . e x e ;. The DOS-sessi on 
window remains open because of /k, 
which tells COMMAND.COM to keep 
the session after the program (roem.exe) 
ran. 

Most of this REXX program deals 
with configuring the virtual machine, 
so the setup string consists of multiple 
SET $o*e_keyvord*.**; statements. You 
can name any setting keyword from 
the settings page of DOS program ob¬ 
jects. If a DOS setting like DQS_UHB has 
just two options, like OK or OFF, you 
would use 1 resp, 0* Otherwise, you 
use string values of the various DOS 
settings verbatim. Multiple entries for 
DOS.DEYICE and DDS.VERSIDH are separated 
with a comma. 

Do not forget to escape commas 
and semicolons with the caret ( A ) if 
they should become part of a setup 
string for a DOS setting (see the DOS 
setting for DOS_VERSIQN in Figure 10). 

One interesting feature of Figure 
10 is hidden in the location for the 
YPProgram object: <YP_NQWIERE>. This lo¬ 
cation does not exist in a visible form 
on the desktop (it is hidden), hence, 
the name nowhere* One could use this 
location for dynamically built objects 
that should not be seen by the user. In 
Figure 10, we use the same OBJECTED to 
open (start) the YPProgram object multi- 
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KEYNAME 

VALUES 

REMARKS 

ASSOCFILTER 

filters 

Set filename filters. 

ASSDCTYPE 

type 

Set association types. 

EKENIHE 

filename 

Program to be executed. 

fttJIBIZED 

YES, (ID 

Maximized upon startup? 

MINIMIZED 

YES, NO 

Minimized upon startup? 

PROGTVPE 

FULLSCREEN 

Full-screen OS/2 session. 


PH 

PM application. 


PRQG_31_ENH 

W1NOS2 3d enhanced mode. 


PROGJl.ENHSEMESSCDNHON 

WTNOS2 3d enhanced mode, seamless common 
session, 


PR 0G,31,EN HS E A M L ESSV DM 

WINOS2 3d enhanced mode seamless session. 


PRQGJl.STD 

WINOS2 3d standard mode. 


progjlstdseahlesscohhon 

WINOS2 3d standard mode, seamless common 
session. 


P R0G_31_ STOSE A ML E SS W DM 

WINOS2 3.1 standard mode, seamless session. 


SEPARATEWIN 

W1NOS2 session in separate VDM. 


VDM 

Full screen DOS session. 


WIN 

Full screen WINOS2 session. 


WINDQWABLEVIO 

Windowed OS/2 session. 


WINDOWEDVDM 

Windowed DOS session. 


UINDOWEDWIN 

Windowed WINOS2 session. 

NOAITOCLOSE 

YES, NO 

Do not dose window upon program! termination? 

PARAMETERS 

pa rams 

Set program parameters. 

SET 


Set environment variables. Set VDM 
characteristics for DOS sessions. 

STARTUPDIR 

pathname 

Set the working directory. 


Figure 9, The Setup String parameters for WPProgram 


/* VPS_NOVH.CMD: demo setting and starting OOS-programs from nowhere*/ 

h change the location to "<WP_DE5KTQP> M to check the settings-page +/ 
location - "<WP_NOVHEf?E> ir /* the "NOYHERP-location */ 

title - "Test of a OOS^Program from noehere 

objectid = "<RGF TEST.DOS.DLltOWNERE>" 

setup = "! PRGGTY PE-WIHDOWEBY DM;" || } 

"EIENAHE**;* 1!, 

"P A RA HE TE RS=/k raaii.exe; “ If, 

"STiRTUPOIfl-TA;" II, 

"SET COM€CEIVEJUFFER,FLGSH=SmCH ID FOREGROUND;' 1 ||, 

"SET ODS_DEVXCE=Vos2\mdos\*NSI.SYS; 11 II, 

"SET DO$.VER$ION=NET)LEIE^%Or ,25V 11, 

"¥1(1200. BIN”, 10* ,10" ,4; ” II, 

"SET &Q$^UHB=1;" II, 

"SET EHS_MEH0RY_LIWn=0;" II, 

"SET IDIE_SEC0NDS*1; M II, 

"SET mE^SENSmm>10;" 11, 

"SET lHS_MEHORY_LIMn^4096;" 11 , 

"0PEN-0£F*ULT; rt II, 

"OBJECTID- 1 if objectid II M ; H 


Figure W, Creating and starting a customized DOS-program from nowhere. (Continued on page 51) 





pie times, so we use the REPLACE option 
on the call to SysCreateObject. In case 
you are interested whether the DOS 
settings have the values expressed in 
Figure 10, merely replace the location 
in SysCreateObject with <WP_DESKT0P> and 
inspect the settings page of it, once the 
ypprogram object has been created. 

A LAST WORD ON miECmS 

Whenever it is possible to supply 
a full path for an object (files that are 
objects or directories which are objects 
representing folders), these full paths 
can be given instead of a WPS OBJECTID. 

Hence, if your boot drive was C; , 
and you have installed the file 
"Enhanced Editor for PM" (EPH.EHE), 
you could use the predefined WPS OBJEC¬ 
TID <WP_EPM> or the C:\QS2\APPS\EPM.EKE 
instead,, the physical location of EPW.EXE 
on your drive C 

Under the application key 
PM J/orkplace:Location in the 0S2.INI file, 
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ok B SysCreateObjectUtfPPrograni”, title, location, setup,, 

"R M ) /* replace, if object exists 

*/ 

Sll "creating:" ojbectid eorked(ok) 

"«PWSE r 


SIT "Cleaning up ..." 

ok = SysOestroyObject(objectid) /* OBJECTED of object 

SIT "destroying (deleting):" objectid worked(ok) 

*/ 

EXXT 


P: 

/* procedure to indicate successful/not successful 

WORKED: PROCEDURE 

IF ARGO) THEN RETURN "successful,” 

ELSE RETURN "*** NOT succesful 

*/ 


Figure Jfc Creating and starting a customized DOS-program from nowhere, (Continued from page 
50.) 


only user-defined OBJ ECHO s of the form 
<some_unique_string> are stored. All WPS 
objects get object handles assigned by 
the WPS, PH_ Work place: Location simply 
serves as a directory that maps user- 
defined DBJECTIDs to their WPS object 
handles. Therefore, objects created 
without an OBJECTU) given in the setup 
string for SysCreateObject would not ap¬ 
pear in this list. The same is true for 


SysCopyQbject and SysCreateShadou. 

Rany G. Ffatscher is an assistant professor in 
the Department of Management information 
Systems, Vienna University of Economics and 
Business Administration, Vienna , Austria, He 
heads the Austrian SIG OS/2 Forum Austria, 
which he helped found He can be reached at e- 
mail RQnyflatscher@wu-wien.ac.at or by tele¬ 
phone (+43) -1-313 36 extension 4881 
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Check out the ftp sites ftp- 
hobbes.nmsu.edu or os2xdrom. 
com for REXX programs/docs 
dealing with the WPS, such as cr- 
tobj.zip or rexxtutzip, A good 
place on the internet is the news- 
group comp.lang.rexx, which gets 
occasional visits from M.F. Cow- 
iishaw (inventor of REXX) and 
Rick McGuire (lead designer for 
the soon to be released follow-up 
to REXX—Object REXX). 

To search WPS- and REXX-related 
programs and docs on the internet 
ftp-sites, you may also use the 
URL http:/ / www,os2forum,or,at/ 
software/htmlmirrors/ entering 
WPS or REXX and choosing the 
appropriate ftp servers. 
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Buyers Guide 



The staff of OS/2 Developer put together this special section to guide you through the 
various REXXproducts available for OS/2. The products in this guide are based on 
surveys sent to vendors; they are provided as a service to you and are free to vendors. 
These listings do not represent an endorsement by OS/2 Developer. Although every 
effort has been made to ensure accuracy, we do not assume any responsibility for 
error or omission in this section. Please contact the companies directly for more 
information. 


REXX Buyers Guide 


OBTECHNOLGIESINC. 

Entry Field Object Pack for VX-REXX 2.13 formats 
entry fields for date, time, telephone, social 
security number, and zip code, A picture object 
is included for special program me redefined 
formats. Compatible with VX-REXX 2.1 or 
higher, this product can be bound to database 
columns via the VX-REXX Client/Server Query 
Object. Price: $49.95. 

Multimedia Object Pack for VX-REXX 1.0.1 

provides objects for the production of profes¬ 
sional OS/2 multimedia applications. It fea¬ 
tures Animated Graphic Pushbuttons, Circular 
Slider, and MCI Object, In addition, program¬ 
mers can control any device manipulated via 
the MCI String command interface. This pack¬ 
age provides real-time synchronous event noti¬ 
fication and is compatible with VX-REXX 2.0 or 
higher. Price: $99, 

VX-Calendar Object 1,0.1 is a programmable 
calendar object for Watcom VX-REXX develop¬ 
ers, Features include drag-and-drop support of 
date information, programmable date ranges, 
changeable day-of-week ordering on the calen¬ 
dar's face, and mulitple font and color support. 
It is compatible with VX-REXX 2,0 or higher. 
Price: $99, 

Enhanced Picture Box Object for VX-REXX 
1.0.0 provides the functionality of the standard 
VX-REXX Picture Box and adds two properties, 
MouseXPos and MouseYPos, that continuously 
report current mouse pointer position. Every 
mouse move on the object generates a 
MouseMove event. This product is compatible 
with VX-REXX 2.0 or higher. Price: $19.95. 

Progress Indicator 0 be jet for VX-REXX 1.0.0 is 
an object for projects requiring progress indi- 
cator bars for file transfers and other lengthy 
procedures. This product features horizontal 


and vertical sizing, multiple font and color 
support, and optional percent text display. It is 
compatible with VX-REXX 2.0 or higher. Price: 
$29.95. 

DB Technologies Inc. 2420 Briar Oak 
Circle, Sarasota, Fla. 34232, (800) 830-8703 or 
(813) 379-8766, fax (813) 377-7392. 

HOCKWAREINC. 

I fisPro/REXX Gold edition 2.11 is a drag-and-drop 
visual programming tool for 32-bit OS/2 2.x 
GUI development. Vis Pro includes all of CUA 
"91 objects plus 3D business graphics and mul¬ 
timedia, full Workplace Shell integration, mul¬ 
tiple threads support, visual DB2/2 database 
designer, multiple development views, SOM- 
based object builder, and it provides stand¬ 
alone, royalty-free executable. LAN version is 
also available. Price: $299.00. 

VtsPro/REXX Bronze edition 2.11 provides 
programmers with an easy-to-use drag-and- 
drop environment to facilitate development for 
32-bit OS/2 2.x GUI applications. It includes 
many of the CUA '91 objects, full Workplace 
Shell integration, multiple development views, 
and SOM-based object builder, and it provides 
standalone, royalty-free executable. An 
upgrade to the Gold edition is available. Price: 
$59. 

Vis/Pro REXX Data Entry Object Pack 1.01 is an 

add-on package of five popular business 
objects for both Vis/Pro REXX Gold and 
Bronze editions. Objects include formatted 
entry field, spreadsheet, split bar, calendar, and 
clock. Price: $89. 

VisPro/Reports 1.01 is a REXX-enabled 
report writer for VisPro/REXX, VX REXX, and 
OS/2 REXX. It allows you to print invoices, 
form letters, personnel reports, financial 
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reports, and so on. A wide variety of Avery labels 
are supported, allowing you to print addresses and 
other labels. A CUA '91 style WYSIWYG report 
designer allows you to include business graphics, 
photographs, calculated fields, multiline text, and 
other cosmetic shapes. Apply numerous object 
attributes, including 16 million colors, OS/2 ATM 
fonts, line styles, line widths, fill patterns, and drop 
shadows. Price: $199. 

Vis Pro Development Suite 2.11 includes 
VisFro/REXX Gold, VisPro/C, and VisPro/C++. 
Price: $499. 

Hock ware Inc., 315 North Academy St., Ste. 100, 
Cary, N.C. 27513, {919) 380-0616, fax (919) 380-0757. 

LESTEC PTY LTD. 

Modular and Integrated Design 1.2 provides a WYSI¬ 
WYG graphic editor for prototyping and designing 
your own ready-to-run PM interface producing sim¬ 
ple reusable dialog scripts (modules). Modules inte¬ 
grate into the OS/2 Desktop and support REXX 
scripts, multithreading, interdialog communication, 
and control for your environment. External C, REXX 
interface, and support for database and external 
communications provided. Price: $199. 

LesTec PTY Ltd., P.O. Box 1394, Dee Why, 
NSW, 2099, Australia 61-2-998-15925, fax 61-2-998- 
15925. 

MANSFIELD SOFTWARE 
GROUP INC. 

KEDIT 5.0 for OS/2 is a general-purpose text editor 
that uses REXX as its macro language. KEDIT, a 32- 
bit text mode application, is compatible with IBM's 
XEDIT editor. Features include selective line editing, 
column editing, undo/redo, file locking, online help, 
SORT command, long filename support, and multi¬ 
ple files and windows. Price: $189. 

Mansfield Software Group Inc., P.O, Box 532, 
Storrs, Conn. 06268, (203) 429-8402, fax (203) 487- 
1185. 

NOMBAS 

CErtvi 2.01 for OS/2 implements the Cmm scripting 
language to enhance batch REXX files, create simple 
personal utilities, and automate program execution. 
Features include full interaction with OS/2 com¬ 
mands, API DLLs, and environment variables; con¬ 
cise documentation; extensive .CMD code library; 
100 examples; compact executable size; and key¬ 
board, menu, dialog, and clipboard automation. 
Price: $45. 

Nombas, 64 Salem St., Medford, Mass. 02155, 
(617) 391-6595, fax (617) 391-3842. 

QUERCUS SYSTEMS 

Personal REXX 3.0 augments OS/2 REXX by including 
REXXLIB extensions for array handling, mathemati¬ 
cal functions, interprocess communication, and gen¬ 


eral system services, hi addition, it provides global 
variables, additional utilities for VM/CMS and 
MVS/TSO compatibility, and enhanced external 
data queue support. Price: $175. 

REXXLIB tO includes over 150 REXX extension 
functions for compound variable handling, inter¬ 
process communication, mathematics, system ser¬ 
vices, and text mode user interfacing. Functions 
include date format conversion, retrieval of com¬ 
pound variable "tails," sorting and other array oper¬ 
ations, "regular expression" searches, and reading or 
writing collections of variables in the disk files. 
There are no run-time fees. Price: $50. 

REXXTERM 2.3 is a full-featured asynchronous 
communications program that provides extensive 
support for user customization and script writing 
with REXX. Other major features include multiple 
dialing directories, built-in text editor, host mode, 
flexible keyboard configuration, VT102 and VT52 
terminal emulation, and Xmodem, Ymodem, 
Zmodem, Kermit, and CompuServe-B file transfer 
protocol. Price: $100. 

Quercus Systems, P.O. Box 2157, Saratoga, Calif. 
95070, (800) 440-5944 or (408) 867-7399, fax (408) 867- 
7489. 

STRATEGIC SOLUTIONS 
INTERNATIONAL CORP. 

Service Point/32 IRS is a fully featured, bidirectional 
service point providing alert generation and 
RUNCMD processing facilities from REXX and C. 
REXX scripts developed on OS/2 platforms are 
interchangeable with host Net View environment for 
RUNCMD processing. Terminal emulation for VT- 
100, ANSI 3.64, and IBM 3164 enable REXX automa¬ 
tion to communicate with outbound management 
systems and generate network management status 
via alerts to NetView, NetMaster, and/or 
Netlmpact. 3270 Panel interface provided in OS/2 
REXX emulates NetView's REXX Panel interface for 
development of user-friendly, full-screen interactive 
application development to front end automated 
commands. Corporate licensing is available. Price: 
$3,000. 

Netlmpact 3R1 f an OS/2-based PM/Workstation, 
provides a GUI for MVS-based SNA/Agent that 
auto-disco vers network and reports availability and 
reliability of managed elements. OS/2 REXX inter¬ 
face provides automation facilities for VTAM and 
MVS commands to address problems with SNA net¬ 
work and with MVS applications. Pricing is based on 
SNA/Agent which includes licenses for PM/ 
Workstations with REXX automation facilities. It 
does not require NetView, but will run if NetView is 
installed. Price: $20,000 (dependent on MVS /ESA 
CPU MIPS). 

Strategic Solutions International Corp., 1127 
Tolland Tnpk., Manchester, Conn. 06040, (203) 649- 
1900, fax (203) 649-1230. 
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VTS-DA TENS YS TEME GMBH & CO. 
REXXLAN/2 2.0 combines the informa¬ 
tion quantity of the LAN Server C-API 
with the advantages of REXX pro¬ 
gramming. Application fields include 
creation of reports from domain con¬ 
troller databases according to specified 
criteria, automation of domain migra¬ 
tions, management of print queues, 
and automated user setup. If server 
applications are to be created with the 
native C-API, REXXLAN/2 allows pro¬ 
totyping and subsequent simple code 
conversion to the final application with 
its identical representation of the data 
structure and functions. Price: about 
$400. 


VTS-Datensysteme GmbH & Co., 
P.O. Box 305583, D-20317 Hamburg, 
Germany, 49-40-656-2856, fax 49-40- 
657-1218. 


LOTUS DEVELOPMENT COBP. 

Ami Pro for OS/2 takes advantage of 
OS/2's multithreading power and 
delivers seamless integration with the 
Workplace Shell, providing drag-and- 
drop document opening, printing and 
shredding, as well 55 professionally- 
designed style sheets for new docu¬ 
ment creation. Inline REXX command 
support included. Fully compatible 
with Ami Pro for Windows Release 3.0. 

Lotus Development Corp., 55 
Cambridge Pkwy., Cambridge, MA 
02142, (617) 577-8500. 

NOMBAS 

CEnvi for OS/2 is a powerful scripting 
tool for OS/2, Windows, and DOS. 
CEnvi executes the CMM (C' minus 
minus) scripting language to enhance 
batch/REXX files, create new utilities, 
or modify and personalize existing 
CEnvi programs written by Nombas 
or other CEnvi users. Hundreds of 
sample programs demonstrate CMM 
programming are included. CEnvi 
provides over 150 internal functions in 
addition to directly linking with all 
DLLs and OS/2 kernel functions. 

Nombas, P.O. Box 875, Medford, 
MA 02115-0007,617 391 6595. 


Chron Co. Hilbert Computing, 
1022 N. Cooper, Olathe, KS 66061, (913) 
780-5051, fax 913-829-2450. 

COMMANDLINE CO. 

CommandLine is a 32-bit on-demand 
command prompt, allowing users to 
execute commands or programs with¬ 
out leaving the active application in 
search of an icon or open session, thus 
eliminating the irritating keyboard- 
mouse-keyboard cycle. The package 
can be invoked via a user-defined hot 
key, and it remembers previous com¬ 
mands across boot sessions and can 
launch DOS and windows applica¬ 
tions. It has aliasing, inline file find, 
filename completion, and an inline 
REXX expression interpreter extendible 
through DLLs. CL also acts as a fast 
task switcher. Any program, command 
or object can be assigned to a hotkey, 
with a variety of options. A hotkey can 
be set to switch to an existing session 
or create a new one. CL can toggle 
between the two most recently used 
windows. Perfect for DEMOs! CL mini¬ 
mizes desktop clutter and simplifies 
access to WPS objects. Users can open 
an object by name, without opening 
nested folders. 

CommandLine Co. Soft & GUI, 
Inc., 2224 East 21st St., Brooklyn, NY 
11229,. 

COMMPAK/2 DYNAMIC LINK LIBRARY, 
PROGRAMMERS TOOLKIT CO. 

Commpak/2 Dynamic Link Library, 
Programmer's Toolkit provides low-, 
medium-, and high-level access to the 
personal computer's asynchronous 
communications port under OS/2 for 
C, C++, and other high-level lan¬ 
guages. It includes everything required 
for manipulating the async port via the 
OS/2 COM.SYS driver, plus X, Y, and 
ZModem file transfer protocols and a 
REXX interface continuously. 

Commpak/2 Dynamic Link 
Library, Programmers Toolkit Co. 
Oberon Software, 1405 East Main St., 
Mankato, MN 56001, 507-388-7001, fax 
507-388-7568. 


CHRON CO. 

Chron is a multithreaded PM applica¬ 
tion that allows flexible operational 
scheduling of workstation or server 
tasks and messages. Events can be 
scheduled One Time or every 'x' min¬ 
utes, hours, days, weeks, months, or 
years. REXX support is added for more 
complex scheduling operations. Chron 
is now CID-enabled for easier installa¬ 
tion. 


FLEXLOAD CO. 

Flexload provides an option to load 
data into as many DBM tables as 
desired simply by designating which 
tables are to be loaded. You may also 
specify the "commit" amount which 
will also improve the load time. You 
will no longer need to maintain multi¬ 
ple REXX programs or other load 
modules since Flexload will automati¬ 
cally rebuild your load program each 


time the destination table structure 
changes. 

Flexload Co. Peregrine Group 
Inc.,The, 200 N. Northwest Highway, 
Barrington, IL 60010. 

FROBOZZ INVESTOR CO. 

Frobozz Investor is a personal invest¬ 
ment application containing four mod¬ 
ules: fund management with graphs, 
portfolio management with ROI calcu¬ 
lation and graph support, technical 
analysis using popular indicators, and 
a REXX interface for data acquisition. It 
also has a REXX interface for external 
access to the database, allowing user 
enhancements. 

Frobozz Investor Co. Frobozz 
Magic Software Co., The, Lange 
Kerkda 113, Wassenaar, 2242 BT, +31 
1751 18301, fax +31 1751 11789. 

GPFREXXCO. 

GpfREXX combines REXX with a power¬ 
ful but easy-to-use, WYSIWYG visual 
programming environment to make 
OS/2 PM programming available to 
almost everyone. Simply point and 
click to design simple utilities or com¬ 
plete applications. It supports standard 
OS/2, as well as multimedia, SQL, and 
advanced communications. 

GpfREXX Co. Apical Software, 
Inc., 40 Falls Rd., PO Box 432, Moodus, 
CT 06469-0432, 203 873 3300, fax 203 
873 3302. 

IBM CORP 

IMS Client/Server/2 lets you incorporate 
your IMS DC or TM application base 
into new, PC-based business solutions. 
To bring your host data to the PC envi¬ 
ronment, IMS CS/2 provides an easy- 
to-use, callable application program¬ 
ming interface (API). IMS CS/2 is 
compatible with VisualAge, DrDialog/ 
DrREXX, Visual C++, PL/I for OS/2 
Toolkit, SmallTalk/VPM, Easel, 
C/C++, Micro Focus COBOL/2, OS/2 
REXX, and Watcom Fortran 77. 

IBM Corp., 555 Bailey Ave., San 
Jose, CA 95142, 800 887 7771, fax 800 
342 6672. 

MANSFIELD SOFTWARE GROUP INC. 
KEDITfor 0S/2v. 5.0 is a powerful, gen¬ 
eral purpose text editor uses REXX as 
its macro language. KEDIT for OS/2, a 
32-bit text mode application, is highly 
compatible with IBM's XEDIT editor. 
Features include: selective line editing, 
column editing, undo/redo, file-lock¬ 
ing, on-line help, SORT command, 
long filename support, multiple files 
and windows, and more. 
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Mansfield Software Group Inc., 
P.O, Box 532, Storrs, CT 06268, (203) 
429-8402, fax (203) 487-1185, 

LESTECPTYLTD 

Modular And Integrated Design (MAID), 
an authoring system, represents 
dialogs as simple script files, providing 
easy access to a powerful GUI front 
end. It makes full use of OS/2 REXX by 
designing object-based dialogs as mod¬ 
ules with object variables as controls, 
using event-driven REXX scripts. 
MAID easily integrates modules with 
each other and your existing programs. 

LESTEC PTY LTD, P.O Box 1394, 
Sydney, 2009, 61-2-99815925, fax 61-2- 
99815925. 

OBERON SOFTWARE 

Oberon Terminal Emulator/2 is a full-fea¬ 
tured, easy-to-use, general purpose 
telecommunications program for 
OS/2. Features include a complete 
script language, optional REXX/2, 200- 
entry dialing directories, call logging, 
split-screen chat mode, and completely 
programmable keyboard. Supports 
XModem and XModem-lK, YModem 
and YModem-G, ZModem, Compu¬ 
Serve B-Plus protocol and ASCII trans¬ 
fer protocols. 

Oberon Software, 1405 East Main 
St., Mankato, MN 56001, 507-388-7001, 
fax 507-388-7568. 

CLEAR St SIMPLE INC, 

Performance Plus V3 is a tuning and util¬ 
ities kit for OS/2 WARP v.3 and 2.1. It 
combines 19 utilities and a 120- page 
book dedicated to OS/2 performance 
tuning. The kit brings power tuning to 
OS/2 users featuring a simple graphic 
user interface. It also tunes 
DOS /Windows applications running 
under OS/2, explaining all of OS/2'$ 
55 DOS settings. The kit contains addi¬ 
tional utilities to measure performance 
and tuning results, simplify bitmap 
viewing, automate file and desktop 
backup, monitor swap file growth with 
audible warning and simplified 
update, create a boot disc or partion, 
and more. It includes an additional 
bonus diskette packed with OS/2 
bitmaps and a CPU Monitor Plus VL. 
The utilities are all written in REXX. 
Ten of the utilities have a GUI interface 
using VisProRexx from Hock ware. 

Clear & Simple Inc., P.O. Box 130, 
W. Simsbury, CT 06092, 203-658-1204, 
fax 203-651-0354. 

QUERCUS SYSTEMS. 

Personal REXX 3.0 for OS/2 is an 


enhanced but fully compatible 32-bit 
implementation of the standard OS/2 
REXX procedures language. It offers 
improved functionality, performance, 
support, and documentation. Its addi¬ 
tional commands and REXX LIB func¬ 
tions perform array sorting, file system 
support, named pipes, interprocess 
communication, global variables, 
mathematics, text-mode user interfac¬ 
ing, and other opera ting-system ser¬ 
vices. 

Personal REXX for Windows is a 

powerful, general-purpose language 
for quick programming tasks, applica¬ 
tion prototyping, and batch file pro¬ 
gramming. REXX has a programming 
interface that allows its use as a gen¬ 
eral-purpose embeddable macro lan¬ 
guage that enables any application to 
utilize REXX as its native scripting ian- 
guage. 

REXXCOMM provides easy access to 
serial ports directly from REXX. Its 
high-level functions support sending 
and receiving data, matching multiple 
character strings, controlling a modem, 
and dialing numbers. Intermediate- 
level functions help manage port con¬ 
figuration parameters, time-out inter¬ 
vals, and RS232 control signals. File 
transfer support includes Xmodem, 
Y modem, Kermit, and CompuServe-B. 

REXXLIB is a function library that 
enhances the OS/2 REXX procedures 
language. It is an extensive toolkit, 
with full access to the advanced capa¬ 
bilities of OS/2, to speed development 
and prototyping of applications. 
Functions are provided for array 
manipulation and sorting, file system 
support, program execution, named 
pipes, interprocess communication, 
data conversion, mathematics, screen 
handling, and other system services. 

Quercus Systems, P.O. Box 2157, 
Saratoga, CA 95070, (408) 867-7399, fax 
(408) 867-7489. 

LEGENTCORP . 

Prevaif/XP Automation Point for OS/2 is a 
workstation-based automated opera¬ 
tions product designed for external 
operation and management of host and 
distributed systems. Prevail/XP 
Automation Point is a general-purpose 
operator workstation that allows an 
operator to view and automatically 
respond to console messages from 
multiple systems at a single focal point. 
Automation is written using expert 
system-based rules and SAA REXX 
procedures. For unattended systems, 
Prevail/XP can notify remote techni¬ 
cians via alphanumeric pagers and 


interactive voice calls. 

Legent Corp., 2000 Park Lane, 
Pittsburgh, PA 15275, (412) 494-1150, 
fax (412) 494-1029. 



SUITABLE ALTERNA TIVES 

REXX Diagnostic Commander's (RDC) 

interactive full-screen source-level 
REXX debugger and diagnostic tool 
allows developers, administrative per¬ 
sonnel, and all OS/2 professionals to 
code and test REXX Execs in a fully 
interactive environment. The interac¬ 
tive display allows the user to single 
step through any type of Exec written 
in REXX. The source code, variables, 
and logic flow can be altered anytime, 
usually with just a keystroke. Changes 
made to the source take immediate 
effect. Permanent changes are accom¬ 
modated by the use of an external edi¬ 
tor. RDC is compatible with IBM-sup- 
plied REXX for OS/2 Release 2.x or 
above. RDC also can be used on 
numerous other platforms, including 
MVS, VM/CMS, and DOS. 

Suitable Alternatives, 4655 Old 
Ironsides Dr., Suite 220, Santa Clara, 
CA 95054, (408) 727-3142, fax (408) 727- 
3170. 


AMERICAN CODERS 

RexxBase provides a complete database 
for REXX programs. RexxBase is an 
external DLL that is called using the 
REXX API. RexxBase can read, write, 
update, DBase DBF, DBT, and NDX 
files. Other functions include SORT, 
JOIN, FILTERS, date handling, and 
more. RexxBase can be used with OS/2 
command files and with the popular 
REXX visual programming packages, 
VisPro/REXX, VX*REXX, and 
GpfREXX. It supports dBase III and IV 
DBF, DBT, NDX, and MDF files. 

American Coders LTD., P.O. Box 
97462, Raleigh, NC 27624, (919) 846- 
2014. 


STRATEGIC SOLUTIONS 
INTERNATIONAL CORP. 

Service Point/32 provides REXX-based 
automation applications and a com¬ 
plete development environment. 
Create standalone or interactive scripts 
to command and control any vendor's 
element management system from 
NetView or SP/32. REXX language 
extensions replicate NetView's auto¬ 
mation environment on OS/2 includ¬ 
ing the 3270-like VIEW panels, 
RUNCMD's, GENALERT's, and 
MSGs. RUNCMD scripts run in 
NetView or SP/32 without modifica¬ 
tion. Optional C language libraries 
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enable SP/32 to be embedded within 
other applications* It requires OS/2 
and either Communications Mana¬ 
ger/2 or ES Communications Manager 
but does not require NetView/FC 
Strategic Solutions International 
Corp., 1075 Tolland Turnpike, Man¬ 
chester, CT 06040, (203) 649-1900, fax 
(203) 649-1230. 


QUO LTD, 

Terminal Manger adds multi-user capa¬ 
bility to OS/2, allowing applications to 
run on low-cost terminals. Terminal 
Manager supports up to 48 terminals, 
each able to run up to 8 text-mode ses¬ 
sions. In each session, the user may 
run any required mix of 16-bit OS/2 
programs, 32-bit OS/2 programs, and 
32-bit REXX applications of most 
MSDOS programs. Operation of the 
host computer's screen and keyboard 
is unaffected. Terminals or PCs may be 
connected, either locally or remotely, 
to COM1-COM8 or to multiport 
adapters. 

Q11Q Ltd., Elm House, 17-19 
Claygate Lane, Surrey, KT7 ODL, 44 
181 339 0739, fax 44 181 398 8443. 


CIRRUS TECHNOLOGY INC. 

Cirrus Technology's Unite Image Viewer 
Object provides the ability to view, 
manipulate, and compress/decom¬ 
press color and gray-scale pho¬ 
tographs and bi-tonal documents. 
Based on IBM's SOM technology, this 
object-oriented tool may be used via 
32-bit APIs or with a front end GUI 
wrapper to integrate the object into 
various visual development environ¬ 
ments, such as WATCOM's VX-REXX 
and IBM's Visual Age, 

The Unite Scanner Object , which 
includes the Unite Image Viewer 
Object, is based on IBM's SOM tech¬ 
nology and provides accessibility to 
functionality available in a wide range 
of scanners including Kodak, Fujitsu, 
Ricoh, and Hewlett-Packard. As a 
development tool for scanning appli¬ 
cations, this object-oriented software 
may be used via 32-bit APIs or with a 
front end GUI wrapper to integrate the 
object into various visual development 
environments such as Watcom's VX- 
REXX and IBM's VisualAge. The Unite 
Scanner Object is developed for the 
IBM OS/2 environment and uses 
ANSI-standard Small Computer 
Systems Interface (SCSI) for connect¬ 


ing peripheral devices and their con¬ 
trollers to microprocessors. 

Cirrus Technology Inc., 5301 
Buckeystown Pike, Frederick, MD 
21701, 301-698-1900, fax 301-698-1909. 

WATCOM 

WATCOM's VX*REXX is an award-win¬ 
ning, easy to use, visual development 
environment for creating OS/2 appli¬ 
cations with GUIs. VX*REXX com¬ 
bines a project management facility, 
visual designer, and an interactive 
source-level debugger to deliver a very 
approachable and highly productive 
visual development environment. 
Package your VX*REXX application as 
an EXE file or PM macro for royalty- 
free redistribution, 

VX*REXX Client/Server Edition is a 
visual development environment for 
creating OS/2 graphical user interface 
applications. It includes all the fea¬ 
tures of VX*REXX V2.1 plus connec¬ 
tion, query and chart objects that allow 
you to access databases, manipulate 
data and chart results quickly and eas¬ 
ily, Features include drag-and-drop 
programming, bound controls, and 
professional multithreaded, multiwin- 
dowed application development. 
Package your VX-REXX application as 
an EXE file or PM macro for royalty- 
free redistribution. 

WATCOM, 415 Phillip St„ 
Waterloo, Ontario N2L 3X2, 519-886- 
3700, fax 519-747-4971. 

HQCKWAREINC . 

VisPro/REXX Bronze provides a low- 
priced entry point to OS/2 GUI pro¬ 
gramming. It is a full-featured, easy- 
to-use visual programming tool that 
lets you build 32-bit standalone GUI 
applications in record time. Features 
include: a visual programming envi¬ 
ronment, drag-and-drop program¬ 
ming that automatically generates 
REXX code, many CUA '91 program¬ 
ming objects, and a SOM toolkit for 
building custom objects. 

VisPro/REXX Gold Edition takes the 
power of OS/2, Workplace Shell, and 
the REXX language and harnesses 
them into an easy-to-use visual pro¬ 
gramming environment. Build 32-bit 
standalone GUI applications in record 
time. It includes everything from the 
Bronze Edition, plus: a full-featured, 
animated graphical debugger, multi¬ 
ple CUA '91 views, access to a DB2 


family of databases, the ability to print 
WYSIWYG, and tabular reports. 

Hock Ware Inc,, P.O. Box 336, 
Cary, NC 27512, (919) 380-0616, fax 
(919) 380-0757. 

DIALOG SOFTWARE GMBH 

WinMgr/PM provides an easy-to-use 
interface for developing standalone or 
client/server applications on local or 
wide area networks (using TCP/IP). It 
provides interfaces to the following 
languages: C, REXX/2, and Komet/ 
PM, but the open design enables the 
use of any other programming lan¬ 
guage. WinMgr/PM can handle all the 
OS/2-PM user in-/output, so that 
your applications have only to react on 
a minimum set of events. 

Dialog Software GmbH, Rosen- 
gartenplatz 7,68161 Mannheim, 

STRATEGIC SOLUTIONS 
INTERNATIONAL CORP 
MVS Application and SNA Network 
Management System . for the Netlmpact 
v, 3R1 OS/2-based PM/Workstation 
provides GUI for the MVS-based 
SNA/Agent that auto-discovers net¬ 
work and reports availability and reli¬ 
ability of managed elements. OS/2 
REXX interface provides automation 
facilities for VTAM and MVS com¬ 
mands to address problems with SNA 
network and with MVS applications. 
Pricing is based on the SNA /Agent, 
which includes licenses for 
PM /Workstations with REXX automa¬ 
tion facilities. 

Strategic Solutions International 
Corp., 1075 Tolland Turnpike, Man¬ 
chester, CT 06040, 203-649-1900, fax 
(203) 649-1230. 

StMMWARE, 

REXXWARE is a robust enterprise man¬ 
agement tool that can also be used to 
build a full suite of custom NetWare 
utilities. It facilitates your migration 
from NetWare 3.x to 4.1. REXXWARE 
gives you access to more than 240 
NetWare operating-system functions. 
Features include: CLIB, Btrieve, 
Bindery, and Directory service calls for 
specific NetWare functions, a com¬ 
piler, a Windows-based scheduler, and 
a dscripts that support access to 
remote servers. 

Simmware, 2 Gurdwara Road, 
Ottawa, Ontario, Canada K2E 1A2, 
(613) 727-1779, fax (613) 727-3533. 
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A Special Repor 
from the 
publishers of 
OS/2 Developer! 

Quantities are limited. 
Order now! 

For fastest service, 
fax your order to us 
at 415-905-4967. J 
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jfiYES! Please send me_ copies of Smalltalk! 

Each copy is only $9.95 in the US or $12.95 in Canada. 

Please add $2.50 for shipping and handling. 

□ Mv check is enclosed 

□ Charge my credit card: □ Visa □ MasterCard □ American 
Express 

Name 

Signature Date 

Send them to: 

Name 
Address 

City State Postal Code 


Mail: Smalltalk 

P. O. Box 7046 
San Francisco 
CA 94120 

Phone: 1-800-444-4881 
Fax: (415) 905-4967 
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Software Development 

October 2-6,1995 Washington, 


Your Mind is Your Livelihood. Feed 


Software Development '95 is the 
most important event of the 
year for cutting-edge develop¬ 
ment professionals. 

Interact with 10,000 of your 
peers and condense months of 
research and learning into a few 
short days. Over 150 lectures, 
workshops and tutorials featur¬ 
ing the industry's leading 
experts cover today's most 
relevant development topics: 


• Team Managers and 
Management 

• Managing for Duality 
and Productivity 

• C++ 

• Windows 95/NT 
Development 

• III Design 

• Building a Software 
Component Strategy 

• Testing and Debugging 


Enterprise Application 
Re-Development 

• Client/Server 
Architectures and 
Tools 

• Database 
Programming 
and Design 

• Object-Oriented 
Programming 

Building Open & 
Distributed Systems 



‘95 East 

D.C. 


it at SD ’95. 

Also see over 300 development 
tools from over 200 leading 
vendors and have your tough 
questions answered by the 
product experts. 

Contact us today for the 
opportunity to increase your 
productivity, enhance the quality 
of your software, and feed your 
mind at SD '95. 


Fax: 

(415)905-2222 

□ Yes! Send me more information on Software Development '95 East. 

Name 

Reply today! 


Mb 

-Company 


Enter your name 

Call: 

Address 

for a chance to 

(800)441-8826 

City 

State 

Zip 

win a FREE 

E-Mail: 

Phone 

Fax E-mail 


SD ‘95 VIP 

sd95east@mfi.com 

^ Home Page http://www.mfi.com/sdconfs/ 

OS2D CDD£ 

Conference Pass. 












